OpenTurtle CLI

OpenTurtle CLI 是一个本地命令行工具。它让你不安装 Desktop，也能使用团队协同、项目上下文、知识库、会议、目标、待办和工作日志，并把 Claude、Codex、Cursor、Qoder、Kiro 接入 OpenTurtle。

命令名是 ot。

给人看的快速开始

从 npm 全局安装：

npm install --global @openturtle/cli

CLI 启动时会在后台检查 npm 新版本，最多每 24 小时检查一次。检查不会阻塞当前命令；发现新版本后会通过 npm 自动完成全局升级，并刷新此前通过 ot install 安装的 Skill、Rule 和 Steering。

也可以手动检查或立即升级：

ot update --check
ot update

需要关闭启动时自动更新时，设置：

export OPENTURTLE_DISABLE_AUTO_UPDATE=1

源码运行、pnpm link 等开发安装不会被自动覆盖。自动更新状态记录在 ~/.openturtle/cli/update.json，Agent 安装记录保存在 ~/.openturtle/cli/installations.json。

临时使用、不全局安装时：

pnpm dlx @openturtle/cli --help

进入你的项目后初始化：

ot init --update-gitignore
ot auth login --web
ot install --target all
ot --json doctor

日常使用：

ot todos list --mine
ot goals list
ot projects list
ot roster list
ot context get --project <project-id>
ot knowledge search "部署"
ot knowledge local search "部署"
ot meetings list --project <project-id>
ot work summary --project <project-id>
ot worklogs show <worklog-id>
ot worklogs list --project <project-id> --to <iso-time> --scope team
ot context get --project <project-id> --query "本周风险"
ot worklogs record --summary "完成联调" --type progress --todo <todo-id>
ot report draft --today

ot install 只安装 CLI 使用指引。Agent 直接执行 ot ... --json，不需要 MCP 或 Hook。

普通项目综合问答优先使用一次聚合 context get，最多再做一次定向补查。日常回答不要使用 --trace、--include-candidates、--help 或全量对象列表；两次读取后仍缺信息时应明确标记“未召回”并停止。trace 只用于召回审计和故障诊断。

常用场景

看我的待办

ot todos list --mine

更新待办进展

ot todos progress <todo-id> --message "完成接口联调，等待验收"

记录一条工作日志

ot worklogs record --summary "完成 Qoder CLI 接入验证" --type progress --todo <todo-id>

聚合搜索知识

ot knowledge search "日报"

默认同时搜索云端知识和本地全文索引。只搜索本地：

ot knowledge search "日报" --local-only
ot knowledge local search "日报"

需要可重复的服务端语料边界时，使用带时区的 --as-of 或不可变快照：

ot knowledge search "日报" --project <project-id> --as-of 2026-07-27T07:28:32Z
ot context get --project <project-id> --query "上次回读验收还有什么缺口" --snapshot <snapshot-id>

使用 --as-of、--snapshot 或任一排除参数时，聚合搜索只返回服务端云端结果，避免无版本边界的本地索引混入；这类参数不能与 --local-only 同时使用。

导出不可变项目快照

创建快照是写操作，先检查 dry-run：

ot projects snapshot export <project-id> \
  --as-of 2026-07-27T07:28:32Z \
  --exclude-tag evaluation-artifact \
  --dry-run
ot projects snapshot list --project <project-id>
ot projects snapshot show <snapshot-id>

快照包含捕获策略、对象版本时间、逐对象内容哈希和 manifest hash。创建后不能更新或删除。

上传录音或文本纪要并处理会议

ot meetings upload ./meeting.m4a --project <project-id> --title "周会"
ot meetings upload ./minutes.txt --project <project-id> --title "周会纪要"  # 已有其他工具生成的纪要归档
ot meetings processing <meeting-id>
ot meetings minutes <meeting-id>

支持 m4a/mp3/wav 录音（ASR 转写）和 txt/md 纯文本纪要（跳过 ASR，直接生成摘要）。

把会议结论同步到项目

ot meetings publish <meeting-id> --dry-run
ot meetings publish <meeting-id>
ot meetings updates list <meeting-id>
ot meetings updates confirm <meeting-id> <update-id> --knowledge <knowledge-id> --dry-run
ot meetings updates confirm <meeting-id> <update-id> --knowledge <knowledge-id>

完整会议纪要先发布为 Knowledge。只有人工查看过项目更新草稿，并拿到已保存的 knowledge_id 后，CLI 才允许确认项目更新。

查看知识来源文件

ot knowledge sources --path docs
ot knowledge source docs/guide.md

生成今天的日报草稿

ot report draft --today

检查安装状态

ot doctor

登录与退出

推荐通过 Web 登录，不需要复制 token：

ot auth login --web

命令会打开 Web Admin，由当前登录账号明确确认授权。只打印链接、不自动打开浏览器：

ot auth login --web --no-open

连接非默认服务时可以指定 API 和 Web 地址：

ot auth login --web --server https://example.com --web-url https://example.com/cli-auth

也可以使用 token 登录：

ot auth login --token <your-token>

默认后端地址是 https://lavertest.kingdee.com/openturtle，可通过 --server 或 OPENTURTLE_SERVER_URL 覆盖。

查看登录状态：

ot auth status

退出：

ot auth logout

给 AI Agent 的完整操作手册

本节是给 AI Agent、自动化脚本和后续维护者看的。人类用户通常只需要阅读上面的快速开始。

1. 基本身份

| 项目 | 值 | | ----------------- | -------------------- | | CLI command | ot | | Package | @openturtle/cli | | Project state dir | .openturtle-cli/ | | Global state dir | ~/.openturtle/cli/ |

重要边界：

• CLI 项目状态只写 .openturtle-cli/
• CLI 全局状态只写 ~/.openturtle/cli/
• 不要创建或写入项目 .openturtle/
• 不要覆盖 Desktop 的 openturtle-automations
• 不要覆盖旧的 openturtle-todo

2. 安装 CLI

在仓库内开发安装：

cd frontend
pnpm install
pnpm --filter @openturtle/cli build
pnpm --filter @openturtle/cli link --global

验证：

command -v ot
ot --help

不全局安装时，可以在 frontend 目录运行：

pnpm --filter @openturtle/cli dev -- --help

构建后可以直接运行：

node apps/cli/dist/index.js --help

3. 初始化工作区

在目标项目根目录执行：

ot init --update-gitignore

期望创建：

.openturtle-cli/
├── config.json
├── state.db
├── drafts/
└── cache/

初始化后执行：

ot doctor

4. 配置认证

优先使用环境变量或 ot auth login。不要把 token 写入代码、README、commit message 或日志。

环境变量：

export OPENTURTLE_SERVER_URL=https://lavertest.kingdee.com/openturtle
export OPENTURTLE_TOKEN=<your-token>

CLI 登录：

ot auth login --web

Web 登录会把 access token 和 refresh token 保存到权限为 0600 的 ~/.openturtle/cli/auth.json。CLI 不读取 Desktop 或浏览器的本地 token。

显式 token 登录：

ot auth login --token <your-token>

用户名密码登录：

ot auth login --username <name> --password <password>

检查：

ot auth status

5. 安装 Agent 接入

安装 Agent 的 CLI Skill、Rule 或 Steering：

ot install --target all

只安装某个目标：

ot install --target claude
ot install --target codex
ot install --target cursor
ot install --target qoder
ot install --target kiro

指定作用域：

ot install --target all --scope project
ot install --target all --scope user

卸载单个 target：

ot uninstall --target git
ot uninstall --target claude
ot uninstall --target codex
ot uninstall --target cursor
ot uninstall --target qoder
ot uninstall --target kiro

纯净卸载全部 OpenTurtle CLI 接入：

ot uninstall --target all

卸载只会删除 CLI 写入的 rule/skill/steering/managed note，以及 .openturtle-cli/ 本地状态目录。它会保留用户自己的 Agent 配置。

安装时会迁移旧版本：删除旧 ot-cli MCP 和 OPENTURTLE-CLI 托管 Hook 条目，同时保留用户自己的 MCP server 和 Hook。ot uninstall --target git 仅作为旧版 Git Hook 的清理入口保留，已经不能再安装 Git Hook。

6. Target 安装矩阵

| Target | 安装内容 | | ------ | ------------------------------- | | Claude | Skill | | Codex | Skill、AGENTS.md managed note | | Cursor | Cursor Rule | | Qoder | Skill | | Kiro | Steering |

7. CLI 接入模型

所有 Agent 都直接执行 ot ... --json。读取命令直接运行；写命令先加 --dry-run 检查请求，再执行正式写入。CLI 本身负责认证、后端访问、稳定 JSON、自动更新，以及升级后刷新已安装的 Agent 指引。

8. 资源命令

项目、团队成员和项目上下文：

ot projects list --keyword "OpenTurtle"
ot projects resolve "OpenTurtle"
ot projects show <project-id> --members
ot roster list
ot roster list --project <project-id>
ot work summary --project <project-id>
ot digest get --project <project-id> --window this_week
ot context get --project <project-id> --query "本周风险" --section risk
ot context get --project <project-id> --query "上次回读验收还有什么缺口" --snapshot <snapshot-id>
# 仅在诊断召回时使用：
ot context get --project <project-id> --query "上次回读验收还有什么缺口" --trace --include-candidates
ot context item meeting <meeting-id> --project <project-id>

可重复读取边界：

ot goals list --project <project-id> --as-of 2026-07-27T07:28:32Z
ot todos list --project <project-id> --exclude-tag evaluation-artifact
ot worklogs list --project <project-id> --exclude-id <worklog-id> --scope team
ot meetings list --project <project-id> --snapshot <snapshot-id>
ot knowledge search "关键词" --project <project-id> --snapshot <snapshot-id>

--exclude-id、--exclude-type 和 --exclude-tag 可重复传入。--snapshot 与 --as-of 或任一排除参数互斥；非法组合会在 CLI 和服务端分别快速失败。服务端 as_of 采用保守语义：对象必须在边界前创建且最后更新时间不晚于边界，WorkLog 的 occurred_at 也必须不晚于边界。

项目快照：

ot projects snapshot export <project-id> --as-of <iso-time> --exclude-tag evaluation-artifact --dry-run
ot projects snapshot list --project <project-id> --page 1 --page-size 20
ot projects snapshot show <snapshot-id>

snapshot export 会持久化不可变 corpus，因此属于写操作；Agent 必须先展示 dry-run，并在用户确认后才执行正式创建。show 会返回完整 manifest/corpus，list 只返回摘要。

目标：

ot goals list --mine
ot goals list --status in_progress
ot goals show <goal-id>
ot goals create --body-file goal.json --dry-run
ot goals create --body-file goal.json
ot goals update <goal-id> --body-file goal-update.json --dry-run

待办：

ot todos list --mine
ot todos list --status pending
ot todos show <todo-id>
ot todos status <todo-id> in_progress
ot todos progress <todo-id> --message "完成接口联调，等待验收"
ot todos create --body-file todo.json --dry-run
ot todos submit-review <todo-id> --body-file review-submission.json --dry-run
ot todos review <todo-id> --body-file review-decision.json --dry-run

Todo 响应的顶层 typed 字段是当前 canonical 值。机器消费者应读取 field_schema_version、canonical_fields 和 metadata_precedence；legacy_metadata 仅保留历史兼容，superseded_fields 指明旧 metadata 键已被哪个顶层字段取代。不得把旧 v0.4 或 J0-J9 metadata 当成当前验收标准。

知识对象：

ot knowledge list
ot knowledge search "日报"
ot knowledge search "日报" --cloud-only
ot knowledge search "日报" --local-only
ot knowledge show <knowledge-id>
ot knowledge relations <knowledge-id>
ot knowledge save --body-file knowledge.json --dry-run
ot knowledge save --body-file knowledge.json
ot knowledge save <knowledge-id> --body-file knowledge-update.json --dry-run
ot knowledge attach <knowledge-id> ./design.pdf ./notes.md --dry-run
ot knowledge attachment-content <knowledge-id> <attachment-id>
ot knowledge attachment-download <knowledge-id> <attachment-id> --output ./design.pdf

来源文件：

ot knowledge sources --path docs
ot knowledge sources --q "WPS"
ot knowledge source docs/guide.md
ot knowledge local list
ot knowledge local search "部署规范"
ot knowledge local read <asset-id>
ot knowledge local import ./docs --dry-run
ot knowledge local create --body-file local-note.json --dry-run
ot knowledge local update <asset-id> --body-file local-note.json --dry-run
ot knowledge local remove <asset-id> --dry-run

ot knowledge search 返回 { query, cloud, local } 聚合结果；--cloud-only 和 --local-only 可限定范围。知识对象是可复用的结论、规范、经验、决策沉淀和操作手册。来源文件是知识背后的原文、附件或仓库文档，本地知识索引可脱离 Desktop 使用。显式服务端边界会自动关闭本地聚合；边界参数与 --local-only 冲突时命令直接报错。

会议：

ot meetings list --project <project-id>
ot meetings upload ./meeting.m4a --project <project-id> --goal <goal-id> --dry-run
ot meetings upload ./meeting.m4a --project <project-id> --goal <goal-id>
ot meetings upload ./minutes.txt --project <project-id>  # txt/md 纪要归档，跳过 ASR
ot meetings processing <meeting-id>
ot meetings transcript <meeting-id>
ot meetings minutes <meeting-id>
ot meetings participants <meeting-id>
ot meetings recording <meeting-id> --output ./meeting.m4a
ot meetings publish <meeting-id>
ot meetings updates list <meeting-id>
ot meetings updates edit <meeting-id> <update-id> --body-file update.json --dry-run
ot meetings updates confirm <meeting-id> <update-id> --knowledge <knowledge-id> --dry-run
ot meetings updates ignore <meeting-id> <update-id> --dry-run

批量确认全部剩余草稿必须显式传 --all。不能同时传更新 ID 和 --all。 录音和附件下载默认拒绝覆盖已有文件；确实要覆盖时显式传 --force。

工作日志：

ot worklogs show <worklog-id>
ot worklogs list --today
ot worklogs list --project <project-id> --to <iso-time> --scope team --page-size 100
ot worklogs list --project <project-id> --window this_week --event-type progress
ot worklogs record --summary "完成 Qoder CLI 接入验证" --type progress --todo <todo-id>
ot worklogs record --summary "Codex CLI 登录需要用户确认" --type blocker
ot worklogs create --body-file worklog.json --dry-run

worklogs list 支持 --project、--from、--to、--event-type、--scope team|managed|mine、--page 和 --page-size。--from / --to 是包含边界，必须是带 Z 或 UTC offset 的 ISO 8601 时间。

--today 等价于 --window today。窗口可选 today、yesterday、this_week、last_week 和 this_month；不传窗口即保持既有全量读取。日历边界按运行 CLI 的系统本地时区计算，再作为 UTC ISO 时间发送给服务端。--today / --window 不能和显式 --from / --to 混用。无效窗口、scope、时间和分页值会在请求前报错。

结构化写操作统一支持 --body-file <json>，也可用 --body-file - 从 stdin 读取。建议先执行同一条命令的 --dry-run，确认 request.path 和 request.body 后再去掉该参数。

只读 API 还提供受限逃生口，只允许 /api/ 下的 GET：

ot request get /api/teams/me
ot request get /api/memory/search --query q=部署 --query limit=5

日报草稿：

ot report draft --today
ot report draft --today --output .openturtle-cli/drafts/today.md

9. AI Agent 推荐流程

当你需要在一个新工作区启用 CLI：

command -v ot
ot init --update-gitignore
ot auth status
ot install --target all
ot --json doctor

然后优先使用高层命令：

ot todos list --mine
ot projects resolve "项目名"
ot context get --project <project-id>
ot meetings list --project <project-id>
ot todos progress <todo-id> --message "..."
ot worklogs record --summary "..." --type progress --todo <todo-id>
ot report draft --today

不要直接改 .openturtle-cli/state.db，除非用户明确要求底层排查。

10. AI Agent 禁止事项

• 不要写项目 .openturtle/
• 不要覆盖 openturtle-automations
• 不要覆盖旧 openturtle-todo
• 不要删除用户已有 Agent 配置
• 不要把 token 写入代码、README、commit 或日志
• 不要安装或调用旧版 OpenTurtle MCP/Hook
• 不要在会议 Knowledge 尚未发布时确认项目更新
• 不要跳过 meetings updates list 直接批量确认会议草稿
• 不要修改 Qoder/Kiro 私有未知格式文件；只写本文列出的配置面

11. JSON 输出约定

CLI 默认输出 JSON，便于 AI Agent 读取。

成功示例：

{
  "initialized": true,
  "project_dir": "/path/to/project/.openturtle-cli"
}

错误会输出到 stderr，并使用非 0 退出码。传全局 --json 时，错误也是稳定 JSON：

{
  "ok": false,
  "error": {
    "code": "api_error",
    "message": "GET /api/teams/me failed: 401",
    "method": "GET",
    "path": "/api/teams/me",
    "status": 401
  }
}

token 不应该被完整打印，auth status 只显示脱敏 token。

12. 开发验证

在 frontend 目录执行：

pnpm --filter @openturtle/cli test
pnpm --filter @openturtle/cli build

打包前检查 tarball 内容：

cd apps/cli
npm pack --dry-run

期望包内只包含 dist/、README.md 和 package.json 等运行所需文件，不包含 src/ 或 test/。

13. npm 自动发布

完整的校验、Trusted Publisher、人工兜底、npm 二次认证、远端 master 对齐和 Skill 刷新检查见 RELEASE_RUNBOOK.md。

.github/workflows/cli-npm-release.yml 会在 master 的 CLI 文件发生变化时运行测试和构建， 然后以仓库版本为最低版本、基于 npm 已发布版本自动递增 patch，发布公开包 @openturtle/cli。

发布使用 npm Trusted Publisher（OIDC），不配置 NPM_TOKEN。在 npm 包的 Settings -> Trusted Publisher 中选择 GitHub Actions，并配置：

• Organization or user：aka-danielZhang
• Repository：openturtle-os
• Workflow filename：cli-npm-release.yml
• Allowed actions：npm publish

@openturtle/cli 首次发布前还没有包设置页面，因此需要维护者通过 npm 登录人工发布一次； 创建包并配置 Trusted Publisher 后，后续 master 发布只使用短期 OIDC 凭证。发布固定使用 https://registry.npmjs.org/，不受开发机 npmmirror 配置影响。

常见问题

我没有安装 Desktop，可以用吗？

可以。CLI 的目标就是让没有 Desktop 的用户也能使用 OpenTurtle。

为什么升级 CLI 后 Skill 也会更新？

ot install 会记录安装过的 target、scope 和工作区。手动执行 ot update 或启动时自动更新 npm 包后，新版 CLI 会重新写入这些 Skill、Rule 和 Steering，并清理旧的 OpenTurtle MCP/Hook 配置。

为什么不用 .openturtle/？

为了避免和 Desktop 等本地能力混在一起。CLI 项目状态只放 .openturtle-cli/。

node:sqlite warning 是什么？

部分 Node 版本会提示内置 SQLite 仍是 experimental。这个 warning 不影响 CLI 测试和基本使用。