@oneworks/cli 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present One Works contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/channel.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+require('@oneworks/cli-helper/entry').runCliPackageEntrypoint({
+  packageDir: __dirname,
+  sourceEntry: './src/channel-cli',
+  distEntry: './dist/channel-cli.js'
+})

package/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+require('@oneworks/cli-helper/entry').runCliPackageEntrypoint({
+  packageDir: __dirname
+})

package/mem.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+require('@oneworks/cli-helper/entry').runCliPackageEntrypoint({
+  packageDir: __dirname,
+  sourceEntry: './src/mem-cli',
+  distEntry: './dist/mem-cli.js'
+})

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@oneworks/cli",
+  "version": "0.1.0-alpha.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oneworks-ai/app.git",
+    "directory": "apps/cli"
+  },
+  "description": "One Works CLI",
+  "imports": {
+    "#~/*.js": {
+      "__oneworks__": {
+        "default": "./src/*.ts"
+      }
+    }
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./config": {
+      "__oneworks__": {
+        "default": "./src/config.ts"
+      },
+      "default": {
+        "import": "./dist/config.mjs",
+        "require": "./dist/config.js"
+      }
+    }
+  },
+  "bin": {
+    "oneworks": "./cli.js",
+    "ow": "./cli.js",
+    "owo": "./cli.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.3",
+    "node-notifier": "^10.0.1",
+    "@oneworks/app-runtime": "0.1.0-alpha.0",
+    "@oneworks/cli-helper": "0.1.0-alpha.0",
+    "@oneworks/config": "0.1.0-alpha.0",
+    "@oneworks/hooks": "0.1.0-alpha.0",
+    "@oneworks/core": "0.1.0-alpha.0",
+    "@oneworks/managed-plugins": "0.1.0-alpha.0",
+    "@oneworks/plugin-cli-skills": "0.1.0-alpha.0",
+    "@oneworks/runtime-protocol": "0.1.0-alpha.0",
+    "@oneworks/types": "0.1.0-alpha.0",
+    "@oneworks/register": "0.1.0-alpha.0",
+    "@oneworks/runtime-store": "0.1.0-alpha.0",
+    "@oneworks/utils": "0.1.0-alpha.0",
+    "@oneworks/workspace-assets": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node-notifier": "^8.0.5"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "pnpm -C ../.. exec vitest run --workspace vitest.workspace.ts --project node apps/cli/__tests__"
+  }
+}

package/postinstall.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process')
+const { existsSync, readFileSync } = require('node:fs')
+const { join, resolve } = require('node:path')
+const process = require('node:process')
+
+const isFalseLike = value => ['0', 'false', 'no', 'off'].includes(String(value ?? '').trim().toLowerCase())
+const isTrueLike = value => ['1', 'true', 'yes', 'on'].includes(String(value ?? '').trim().toLowerCase())
+
+const shouldSkip = () => (
+  isTrueLike(process.env.ONEWORKS_SKIP_POSTINSTALL) ||
+  isTrueLike(process.env.ONEWORKS_SKIP_ADAPTER_PREPARE) ||
+  process.env.ONEWORKS_ADAPTER_PREPARE_POSTINSTALL_ACTIVE === '1' ||
+  (
+    process.env.CI != null &&
+    !isFalseLike(process.env.CI) &&
+    !isTrueLike(process.env.ONEWORKS_POSTINSTALL_PREPARE)
+  )
+)
+
+const isPlainObject = value => value != null && typeof value === 'object' && !Array.isArray(value)
+
+const readJsonConfig = projectDir => {
+  for (const relativePath of ['.oo.config.json', 'infra/.oo.config.json']) {
+    const configPath = join(projectDir, relativePath)
+    if (!existsSync(configPath)) continue
+    try {
+      return JSON.parse(readFileSync(configPath, 'utf8'))
+    } catch (error) {
+      console.warn(`[oneworks] Skipping adapter CLI postinstall prepare: failed to read ${relativePath}.`)
+      console.warn(error instanceof Error ? error.message : String(error))
+      return undefined
+    }
+  }
+  return undefined
+}
+
+const hasPrepareOnInstallTarget = config => {
+  const adapters = isPlainObject(config?.adapters) ? config.adapters : undefined
+  if (adapters == null) return false
+
+  return Object.values(adapters).some(adapterConfig => {
+    if (!isPlainObject(adapterConfig)) return false
+    return ['cli', 'routerCli'].some(key => (
+      isPlainObject(adapterConfig[key]) && adapterConfig[key].prepareOnInstall === true
+    ))
+  })
+}
+
+if (!shouldSkip()) {
+  const projectDir = resolve(process.env.INIT_CWD || process.cwd())
+  const config = readJsonConfig(projectDir)
+  if (hasPrepareOnInstallTarget(config)) {
+    const result = spawnSync(
+      process.execPath,
+      [join(__dirname, 'cli.js'), 'adapter', 'prepare', '--from-postinstall'],
+      {
+        cwd: projectDir,
+        env: {
+          ...process.env,
+          ONEWORKS_ADAPTER_PREPARE_POSTINSTALL_ACTIVE: '1'
+        },
+        stdio: 'inherit'
+      }
+    )
+
+    if (result.status !== 0) {
+      const strict = isTrueLike(process.env.ONEWORKS_POSTINSTALL_STRICT)
+      console.warn('[oneworks] Adapter CLI postinstall prepare failed.')
+      if (strict) {
+        process.exit(result.status ?? 1)
+      }
+    }
+  }
+}

package/src/AGENTS.md

@@ -0,0 +1,169 @@
+# CLI Src 目录说明
+
+CLI 侧只负责命令入口、参数归并、hook/plugin 调用、agent runtime command 写入与把任务交给 app-facing runtime / adapter。
+app-facing 的 task / benchmark 入口位于 `@oneworks/app-runtime`。
+MCP stdio server 入口位于 `@oneworks/mcp`。
+默认内建 `OneWorks` MCP 的解析位于 `@oneworks/config`，由 task runtime 在 prepare 阶段注入，但不承担 task domain；发布态的 `@oneworks/mcp` 安装锚点由 `@oneworks/app-runtime` 提供。
+agent runtime 标准入口是 `oneworks --input-format json|stream-json --output-format json|stream-json` 的 runtime protocol mode；`oneworks agent ...` 是 runtime protocol command 入口。命令写入 runtime protocol/store 后由 runtime consumer 处理。
+adapter 契约与 loader 位于 `@oneworks/types`。
+task-facing workspace asset helper 位于 `@oneworks/workspace-assets`。
+definition loader 位于 `@oneworks/definition-loader`。
+通用 hooks runtime、`oneworks-call-hook` 与 native helper 位于 `@oneworks/hooks`。
+`defineConfig()`、通用配置加载、默认 system prompt 策略和默认内建 MCP 解析位于 `@oneworks/config`，共享 logger / log-level / key-transform / system helper / model-selection / cache 位于 `@oneworks/utils`。
+config、cache、definition、workspace asset 共享 contract 位于 `@oneworks/types`。
+
+## 什么时候先读这里
+
+- 用户问题是通过 `npx oneworks ...` 复现出来的
+- 想知道某个命令最终调用了哪个 adapter / runtime
+- `init`、`run --print`、hook/plugin logger 的行为不符合预期
+- 想确认环境变量是从 CLI 哪一层注入进去的
+
+文档交叉入口：
+
+- `.oo/rules/HOOKS.md`
+- `.oo/rules/HOOKS-REFERENCE.md`
+- `packages/types/AGENTS.md`
+- `packages/app-runtime/AGENTS.md`
+- `packages/workspace-assets/AGENTS.md`
+- `packages/mcp/AGENTS.md`
+- `packages/task/AGENTS.md`
+- `packages/adapters/codex/AGENTS.md`
+- `packages/adapters/claude-code/AGENTS.md`
+- `packages/adapters/opencode/AGENTS.md`
+
+优先入口：
+
+- `commands/run.ts`
+- `commands/agent.ts`
+- `commands/agent/*`
+- `../../packages/hooks/src/entry.ts`
+- `../../packages/cli-helper/loader.js`
+- `../../packages/hooks/call-hook.js`
+
+## Hooks bridge 入口
+
+hooks 相关问题先按这条链路看：
+
+- `packages/hooks/call-hook.js`
+  - 通用 hook 进程入口
+  - 负责把 `HOME` 指到 home project 下的 `.mock`，再执行 hooks runtime
+- `packages/hooks/src/entry.ts`
+  - 动态发现已安装 adapter 的 `./hook-bridge`，命中 active env 后执行，否则回退默认 `runHookCli()`
+- `packages/hooks/src/runtime.ts`
+  - 默认 hook runtime，负责读取输入、装载插件、执行 middleware
+- `packages/config/src/load.ts`
+  - hooks runtime 的配置读取、变量替换与缓存
+- `packages/utils/src/create-logger.ts`
+  - hooks runtime 与主会话共用的 markdown logger
+- `packages/utils/src/string-transform.ts`
+  - hook 输入 key 转换
+- `packages/adapters/claude-code/src/hook-bridge.ts`
+  - Claude native payload -> 统一 hook input/output
+- `packages/adapters/codex/src/hook-bridge.ts`
+  - Codex native payload -> 统一 hook input/output
+
+维护约定：
+
+- CLI 只做入口分发和最小 env 补齐，不承载 adapter 私有协议翻译
+- adapter-native plugin 的标准安装动作、目录约定和失败回滚在 CLI core；adapter 自己的 `./plugins` 导出只提供 native 格式解析、marketplace 规则和转换钩子
+- 业务 hook 执行放在 `packages/hooks/src/*`
+- 通用 `call-hook.js` 运行时与 `oneworks-call-hook` bin 都归 `packages/hooks`
+- project mock home 的 native 资产写入放在 adapter / `packages/hooks/src/native.ts`，不要散落到 CLI 命令层
+- 真实 adapter E2E 验证优先走仓库根的 `pnpm test:e2e:adapters`
+- 定向排查时走 `pnpm tools adapter-e2e run <selection>`
+- `pnpm test:e2e:adapters` 和 `pnpm tools adapter-e2e run <selection>` 默认都会起本地 mock LLM server；对应模型服务配置在仓库根 `.oo.config.json`
+  - `hook-smoke-mock` 给 Codex / OpenCode
+  - `hook-smoke-mock-ccr` 给 Claude Code Router
+- adapter E2E 的 shared harness 在 `scripts/adapter-e2e/`，scripts CLI 入口在 `scripts/cli.ts`
+- 新增场景优先改 `scripts/__tests__/adapter-e2e/cases.ts` 和 `mock-llm/rules.ts`，不要再往脚本入口堆逻辑
+- 真实 CLI 结果统一写进 Vitest file snapshot；更新时用 `pnpm tools adapter-e2e test <case-id> --update`
+
+## 什么时候继续往下读别的目录
+
+### 1. 看到的是命令入口问题
+
+继续留在本目录：
+
+- `commands/*.ts`
+- `hooks/*.ts`
+
+适合排查：
+
+- 参数没有传下去
+- `sessionId` / `ctxId` 生成不对
+- `--print` / `--resume` / `--spec` / `--entity` / `--no-default-oneworks-mcp-server` 行为异常
+- runtime protocol mode 或 `oneworks agent start/send/stop/kill/submit/resume/status/events` 行为异常
+
+### 2. 看到的是 agent runtime protocol/store 问题
+
+转到：
+
+- `commands/agent.ts`
+- `commands/agent/*`
+- `packages/runtime-protocol`
+- `packages/runtime-store`
+- `packages/task-runtime`
+
+原因：
+
+- CLI 负责把 runtime protocol envelope 或 `oneworks agent ...` 参数转换为 runtime command / status / event 读写
+- task domain 不通过 MCP 暴露，也不维护 MCP 到 runtime protocol 的转换层
+- server 和 UI 依赖 runtime store projection，不直接消费 CLI stdout 作为长期状态源
+
+### 3. 看到的是主会话日志级别问题
+
+转到：
+
+- `packages/task/src/prepare.ts`
+- `packages/utils/src/create-logger.ts`
+- `packages/utils/src/log-level.ts`
+- `packages/core/src/env.ts`
+
+原因：
+
+- CLI 只是把环境变量和 runtime 带入 task
+- 真正决定主会话 markdown 日志怎么写的是 `packages/utils` 加 `task prepare`
+
+### 4. 看到的是 Claude Code adapter / CCR / transformer 问题
+
+转到：
+
+- `packages/adapters/claude-code/AGENTS.md`
+
+进入条件：
+
+- `Claude Code CLI stdout` 日志内容不对
+- CCR transformer 日志文件缺失或异常
+- create/resume 流程不对
+- adapter CLI 参数、settings、mcp config 需要追踪
+
+### 5. 看到的是独立 MCP server 问题
+
+转到：
+
+- `packages/mcp/AGENTS.md`
+- `packages/mcp/src/cli.ts`
+- `packages/mcp/src/command.ts`
+
+进入条件：
+
+- `oneworks-mcp` 无法启动
+- MCP tools 注册/过滤不对
+- 非 task MCP tool 结果异常，例如 `AskUserQuestion`
+
+### 6. 看到的是 server 控制台 / session jsonl 问题
+
+转到：
+
+- `apps/server/src/utils/logger.ts`
+- `apps/server/src/AGENTS.md`
+
+## CLI 调试建议
+
+- 复现前先执行 `npx oneworks clear`
+- 独立 MCP server 冒烟先执行 `oneworks-mcp --help`
+- 如果只想看本次日志，先 `touch /tmp/<marker>` 再执行命令
+- `run --print` 的最终 session 行为由 task + adapter 决定，CLI 只负责入口编排，不要在 CLI 里追完整生命周期
+- CLI loader 共享实现位置：`packages/cli-helper/loader.js`
+- 适配器错误 / `stream-json` 冒烟流程见：`.oo/rules/adapter-error-debugging.md`

package/src/channel-cli.ts

@@ -0,0 +1,19 @@
+import process from 'node:process'
+
+import { Command } from 'commander'
+
+import { getCliVersion } from '#~/utils.js'
+
+import { registerChannelSubcommands } from './commands/channel'
+
+const program = new Command()
+
+program
+  .name('oneworks channel')
+  .description('Send messages through OneWorks channels from agent sessions')
+  .version(getCliVersion())
+  .showHelpAfterError()
+
+registerChannelSubcommands(program)
+
+program.parse(process.argv)

package/src/cli-argv.ts

@@ -0,0 +1,27 @@
+const ROOT_ONLY_ARGS = new Set(['-h', '--help', '-V', '--version', 'help'])
+const ROOT_SUBCOMMANDS = new Set([
+  'agent',
+  'adapter',
+  'benchmark',
+  'channel',
+  'clear',
+  'config',
+  'kill',
+  'list',
+  'ls',
+  'mem',
+  'plugin',
+  'report',
+  'skills',
+  'stop'
+])
+
+export const normalizeCliArgs = (args: string[]) => {
+  const [firstArg] = args
+
+  if (firstArg == null) return ['__run']
+  if (ROOT_ONLY_ARGS.has(firstArg)) return args
+  if (!firstArg.startsWith('-') && ROOT_SUBCOMMANDS.has(firstArg)) return args
+
+  return ['__run', ...args]
+}

package/src/cli.ts

@@ -0,0 +1,63 @@
+import './commands/@core/extra-options'
+
+import process from 'node:process'
+
+import { program } from 'commander'
+
+import { getCliDescription, getCliVersion } from '#~/utils.js'
+
+import { normalizeCliArgs } from './cli-argv'
+import { registerAccountsCommand } from './commands/accounts'
+import { registerAdapterCommand } from './commands/adapter'
+import { registerAgentCommand } from './commands/agent'
+import { registerBenchmarkCommand } from './commands/benchmark'
+import { registerChannelCommand } from './commands/channel'
+import { registerClearCommand } from './commands/clear'
+import { registerConfigCommand } from './commands/config'
+import { registerKillCommand } from './commands/kill'
+import { registerListCommand } from './commands/list'
+import { registerMemoryCommand } from './commands/memory'
+import { registerPluginCommand } from './commands/plugin'
+import { registerReportCommand } from './commands/report'
+import { registerRunCommand } from './commands/run'
+import { registerSkillsCommand } from './commands/skills'
+import { registerStopCommand } from './commands/stop'
+
+program
+  .name('oneworks')
+  .description(getCliDescription())
+  .version(getCliVersion())
+  .showHelpAfterError()
+  .addHelpText(
+    'after',
+    `
+Examples:
+  oneworks 读取 README 并给出改进建议
+  oneworks --include-skill oneworks-cli-quickstart 介绍 One Works CLI 的常用命令
+  oneworks 帮我创建一个前端评审实体
+  oneworks list
+  oneworks list --view full
+  oneworks config list
+  oneworks --resume [sessionId]
+  oneworks --fork [sessionId]
+  oneworks list --running
+`
+  )
+
+registerRunCommand(program)
+registerAccountsCommand(program)
+registerAgentCommand(program)
+registerAdapterCommand(program)
+registerBenchmarkCommand(program)
+registerChannelCommand(program)
+registerClearCommand(program)
+registerConfigCommand(program)
+registerListCommand(program)
+registerPluginCommand(program)
+registerReportCommand(program)
+registerStopCommand(program)
+registerSkillsCommand(program)
+registerKillCommand(program)
+registerMemoryCommand(program)
+
+program.parse(normalizeCliArgs(process.argv.slice(2)), { from: 'user' })

package/src/commands/@core/adapter-option.ts

@@ -0,0 +1,85 @@
+import { Option } from 'commander'
+
+import { normalizeAdapterPackageId } from '@oneworks/types'
+
+const ADAPTER_PREFIX = 'adapter-'
+
+export interface CliAdapterOptionValue {
+  adapter: string
+  cliVersion?: string
+}
+
+const splitAdapterVersionSelector = (value: string) => {
+  const lastAt = value.lastIndexOf('@')
+  if (lastAt <= 0) {
+    return {
+      adapter: value
+    }
+  }
+
+  if (value.startsWith('@')) {
+    const slash = value.indexOf('/')
+    if (slash < 0 || lastAt <= slash) {
+      return {
+        adapter: value
+      }
+    }
+  }
+
+  const adapter = value.slice(0, lastAt).trim()
+  const cliVersion = value.slice(lastAt + 1).trim()
+  if (adapter === '' || cliVersion === '') {
+    throw new TypeError('Adapter version selector must be formatted as <adapter>@<version>.')
+  }
+  if (/\s/.test(cliVersion)) {
+    throw new TypeError('Adapter CLI version must not contain whitespace.')
+  }
+
+  return {
+    adapter,
+    cliVersion
+  }
+}
+
+export const parseCliAdapterOptionValue = (value: string): CliAdapterOptionValue => {
+  const trimmed = value.trim()
+  if (trimmed === '') {
+    return {
+      adapter: trimmed
+    }
+  }
+
+  const selector = splitAdapterVersionSelector(trimmed)
+  const normalized = normalizeAdapterPackageId(selector.adapter)
+  const adapter = normalized.startsWith(ADAPTER_PREFIX)
+    ? normalized.slice(ADAPTER_PREFIX.length)
+    : normalized
+
+  return {
+    adapter,
+    cliVersion: selector.cliVersion
+  }
+}
+
+export const normalizeCliAdapterOptionValue = (value: string) => {
+  return parseCliAdapterOptionValue(value).adapter
+}
+
+const normalizeCliAdapterSelectorOptionValue = (value: string) => {
+  const parsed = parseCliAdapterOptionValue(value)
+  return parsed.cliVersion == null ? parsed.adapter : `${parsed.adapter}@${parsed.cliVersion}`
+}
+
+export const createAdapterOption = (
+  description: string,
+  options?: {
+    allowCliVersion?: boolean
+  }
+) => (
+  new Option('-A, --adapter <adapter>', description)
+    .argParser(
+      options?.allowCliVersion === true
+        ? normalizeCliAdapterSelectorOptionValue
+        : normalizeCliAdapterOptionValue
+    )
+)

package/src/commands/@core/extra-options.ts

@@ -0,0 +1,12 @@
+import process from 'node:process'
+
+// 获取通过 -- 参数传递的额外选项
+const extraOptionsStartIndex = process.argv.indexOf('--')
+export const extraOptions = extraOptionsStartIndex !== -1
+  ? process.argv.slice(extraOptionsStartIndex + 1)
+  : []
+
+if (extraOptions.length > 0) {
+  // 删除 process.argv 中的额外选项
+  process.argv.splice(extraOptionsStartIndex, extraOptions.length + 1)
+}

package/src/commands/@core/plugin-install.ts

@@ -0,0 +1 @@
+export { addAdapterPlugin, installAdapterPluginWithInstaller } from '@oneworks/managed-plugins'

package/src/commands/@core/plugin-source.ts

@@ -0,0 +1 @@
+export { installManagedPluginSource, pathExists, resolveManagedPluginSource } from '@oneworks/managed-plugins'