@openturtle/cli 0.3.0

package/README.md

@@ -0,0 +1,674 @@
+# OpenTurtle CLI
+
+OpenTurtle CLI 是一个本地命令行工具。它让你不安装 Desktop，也能使用团队协同、项目上下文、知识库、会议、目标、待办和工作日志，并把 Claude、Codex、Cursor、Qoder、Kiro 接入 OpenTurtle。
+
+命令名是 `ot`。
+
+## 给人看的快速开始
+
+从 npm 全局安装：
+
+```bash
+npm install --global @openturtle/cli
+```
+
+临时使用、不全局安装时：
+
+```bash
+pnpm dlx @openturtle/cli --help
+```
+
+进入你的项目后初始化：
+
+```bash
+ot init --update-gitignore
+ot auth login --web
+ot install --target all
+ot --json doctor
+```
+
+日常使用：
+
+```bash
+ot todos list --mine
+ot goals list
+ot projects list
+ot roster list
+ot context get --project <project-id>
+ot knowledge search "部署"
+ot meetings list --project <project-id>
+ot worklogs record --summary "完成联调" --type progress
+ot report draft --today
+```
+
+如果你希望 AI 工具自动帮你记录开发过程，再执行：
+
+```bash
+ot install --target all --with-agent-hooks
+```
+
+hooks 只负责记录，不会阻止提交代码，也不会改变 AI 工具原本的行为。
+
+## 常用场景
+
+### 看我的待办
+
+```bash
+ot todos list --mine
+```
+
+### 更新待办进展
+
+```bash
+ot todos progress <todo-id> --message "完成接口联调，等待验收"
+```
+
+### 记录一条工作日志
+
+```bash
+ot worklogs record --summary "完成 Qoder hook 接入验证" --type progress
+```
+
+### 搜索知识
+
+```bash
+ot knowledge search "日报"
+```
+
+### 上传录音并处理会议
+
+```bash
+ot meetings upload ./meeting.m4a --project <project-id> --title "周会"
+ot meetings processing <meeting-id>
+ot meetings minutes <meeting-id>
+```
+
+### 把会议结论同步到项目
+
+```bash
+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 才允许确认项目更新。
+
+### 查看知识来源文件
+
+```bash
+ot knowledge sources --path docs
+ot knowledge source docs/guide.md
+```
+
+### 生成今天的日报草稿
+
+```bash
+ot report draft --today
+```
+
+### 检查安装状态
+
+```bash
+ot doctor
+```
+
+## 登录与退出
+
+推荐通过 Web 登录，不需要复制 token：
+
+```bash
+ot auth login --web
+```
+
+命令会打开 Web Admin，由当前登录账号明确确认授权。只打印链接、不自动打开浏览器：
+
+```bash
+ot auth login --web --no-open
+```
+
+连接非默认服务时可以指定 API 和 Web 地址：
+
+```bash
+ot auth login --web --server https://example.com --web-url https://example.com/cli-auth
+```
+
+也可以使用 token 登录：
+
+```bash
+ot auth login --token <your-token>
+```
+
+默认后端地址是 `https://lavertest.kingdee.com/openturtle`，可通过 `--server` 或
+`OPENTURTLE_SERVER_URL` 覆盖。
+
+查看登录状态：
+
+```bash
+ot auth status
+```
+
+退出：
+
+```bash
+ot auth logout
+```
+
+## 给 AI Agent 的完整操作手册
+
+本节是给 AI Agent、自动化脚本和后续维护者看的。人类用户通常只需要阅读上面的快速开始。
+
+### 1. 基本身份
+
+| 项目              | 值                   |
+| ----------------- | -------------------- |
+| CLI command       | `ot`                 |
+| Package           | `@openturtle/cli`    |
+| MCP server name   | `ot-cli`             |
+| Project state dir | `.openturtle-cli/`   |
+| Global state dir  | `~/.openturtle/cli/` |
+
+重要边界：
+
+- CLI 项目状态只写 `.openturtle-cli/`
+- CLI 全局状态只写 `~/.openturtle/cli/`
+- 不要创建或写入项目 `.openturtle/`
+- 不要覆盖 Desktop 的 `openturtle-knowledge`
+- 不要覆盖 Desktop 的 `openturtle-automations`
+- 不要覆盖旧的 `openturtle-todo`
+
+### 2. 安装 CLI
+
+在仓库内开发安装：
+
+```bash
+cd frontend
+pnpm install
+pnpm --filter @openturtle/cli build
+pnpm --filter @openturtle/cli link --global
+```
+
+验证：
+
+```bash
+command -v ot
+ot --help
+```
+
+不全局安装时，可以在 `frontend` 目录运行：
+
+```bash
+pnpm --filter @openturtle/cli dev -- --help
+```
+
+构建后可以直接运行：
+
+```bash
+node apps/cli/dist/index.js --help
+```
+
+### 3. 初始化工作区
+
+在目标项目根目录执行：
+
+```bash
+ot init --update-gitignore
+```
+
+期望创建：
+
+```text
+.openturtle-cli/
+├── config.json
+├── state.db
+├── hooks/
+├── drafts/
+└── cache/
+```
+
+初始化后执行：
+
+```bash
+ot doctor
+```
+
+### 4. 配置认证
+
+优先使用环境变量或 `ot auth login`。不要把 token 写入代码、README、commit message 或日志。
+
+环境变量：
+
+```bash
+export OPENTURTLE_SERVER_URL=https://lavertest.kingdee.com/openturtle
+export OPENTURTLE_TOKEN=<your-token>
+```
+
+CLI 登录：
+
+```bash
+ot auth login --web
+```
+
+Web 登录会把 access token 和 refresh token 保存到权限为 `0600` 的 `~/.openturtle/cli/auth.json`。CLI 不读取 Desktop 或浏览器的本地 token。
+
+显式 token 登录：
+
+```bash
+ot auth login --token <your-token>
+```
+
+用户名密码登录：
+
+```bash
+ot auth login --username <name> --password <password>
+```
+
+检查：
+
+```bash
+ot auth status
+```
+
+### 5. 安装 Agent 接入
+
+默认安装 MCP、rules/skills 和 Git hook，不安装 Agent hooks：
+
+```bash
+ot install --target all
+```
+
+安装 Agent hooks：
+
+```bash
+ot install --target all --with-agent-hooks
+```
+
+只安装某个目标：
+
+```bash
+ot install --target git
+ot install --target claude
+ot install --target codex
+ot install --target cursor
+ot install --target qoder
+ot install --target kiro
+```
+
+指定作用域：
+
+```bash
+ot install --target all --scope project
+ot install --target all --scope user
+```
+
+卸载单个 target：
+
+```bash
+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 接入：
+
+```bash
+ot uninstall --target all
+```
+
+卸载只会删除 `ot-cli` MCP server、`OPENTURTLE-CLI` 托管 hook、CLI 写入的 rule/skill/steering/agent 文件，以及 `.openturtle-cli/` 本地状态目录。它会保留非 OpenTurtle 配置、用户自己的 hook、Desktop/旧版 MCP server，例如 `openturtle-knowledge`、`openturtle-automations`、`openturtle-todo`。
+
+如果 Git 原来已有 `post-commit` hook，卸载会恢复原 hook，然后删除 OpenTurtle CLI 的备份文件。
+
+### 6. Target 安装矩阵
+
+| Target | 默认安装                                      | `--with-agent-hooks`                                                          |
+| ------ | --------------------------------------------- | ----------------------------------------------------------------------------- |
+| Git    | `.git/hooks/post-commit`                      | 同默认                                                                        |
+| Claude | `ot-cli` MCP、Skill                           | `UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`                       |
+| Codex  | `ot-cli` MCP、Skill、`AGENTS.md` managed note | `PreToolUse`、`PostToolUse`、`Stop`                                           |
+| Cursor | project `.mcp.json`、Cursor Rule              | `preToolUse`、`postToolUse`                                                   |
+| Qoder  | MCP、Skill                                    | `UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`Stop` |
+| Kiro   | MCP、Steering                                 | `agentSpawn`、`userPromptSubmit`、`preToolUse`、`postToolUse`、`stop`         |
+
+Qoder 和 Kiro 支持 native hook。CLI 仍保留 `import-history` 和 `watch`，用于补齐旧会话或未启用 hook 的环境。
+
+### 7. Hooks 的作用
+
+hooks 是本地记录入口。它们把开发过程写入 `.openturtle-cli/state.db`，用于工作日志、待办进展证据和日报草稿。
+
+会记录：
+
+- Git commit
+- 用户提交给 Agent 的 prompt
+- Agent tool call 前后
+- Agent tool call 失败
+- Agent session stop
+- history import 记录
+
+不会做：
+
+- 不阻止 Git commit
+- 不阻止 Agent tool call
+- 不替用户批准危险操作
+- 不上传私有文件内容
+- 不修改 Desktop MCP server
+
+Git hook 会保留已有 hook。原 hook 的退出码会保留，OpenTurtle 采集失败不会改变 commit 结果。
+
+### 8. MCP server
+
+MCP server 名固定为：
+
+```text
+ot-cli
+```
+
+启动：
+
+```bash
+ot mcp serve
+```
+
+tools：
+
+```text
+list_my_todos
+list_goals
+list_workspace_knowledge
+search_workspace_knowledge
+list_knowledge_source_files
+read_knowledge_source_file
+record_worklog
+list_worklogs
+draft_daily_report
+update_todo_progress
+update_todo_status
+```
+
+`list_workspace_knowledge` / `search_workspace_knowledge` 查询可复用知识对象。`list_knowledge_source_files` / `read_knowledge_source_file` 只查看知识背后的来源文件或原文文件，不把来源文件当成第二套知识库。
+
+MCP tools 优先访问 OpenTurtle API。云端不可用时，尽量返回本地缓存或本地草稿信息，并标记 `source: "local_cache"`。
+
+MCP smoke test：
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | ot mcp serve
+```
+
+期望 `serverInfo.name` 是 `ot-cli`。
+
+### 9. 资源命令
+
+项目、团队成员和项目上下文：
+
+```bash
+ot projects list --keyword "OpenTurtle"
+ot projects resolve "OpenTurtle"
+ot projects show <project-id> --members
+ot roster list
+ot context get --project <project-id> --query "本周风险" --section risk
+ot context item meeting <meeting-id> --project <project-id>
+```
+
+目标：
+
+```bash
+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
+```
+
+待办：
+
+```bash
+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
+```
+
+知识对象：
+
+```bash
+ot knowledge list
+ot knowledge search "日报"
+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
+```
+
+来源文件：
+
+```bash
+ot knowledge sources --path docs
+ot knowledge sources --q "WPS"
+ot knowledge source docs/guide.md
+```
+
+知识对象是可复用的结论、规范、经验、决策沉淀和操作手册。来源文件是知识背后的原文、附件或仓库文档。
+
+会议：
+
+```bash
+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 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`。
+
+工作日志：
+
+```bash
+ot worklogs list --today
+ot worklogs record --summary "完成 Qoder hook 接入验证" --type progress
+ot worklogs record --summary "Codex hook trust 需要用户确认" --type blocker
+ot worklogs create --body-file worklog.json --dry-run
+```
+
+结构化写操作统一支持 `--body-file <json>`，也可用 `--body-file -` 从 stdin 读取。建议先执行同一条命令的 `--dry-run`，确认 `request.path` 和 `request.body` 后再去掉该参数。
+
+只读 API 还提供受限逃生口，只允许 `/api/` 下的 GET：
+
+```bash
+ot request get /api/teams/me
+ot request get /api/memory/search --query q=部署 --query limit=5
+```
+
+日报草稿：
+
+```bash
+ot report draft --today
+ot report draft --today --output .openturtle-cli/drafts/today.md
+```
+
+### 10. 历史导入与监听
+
+一次性导入：
+
+```bash
+ot import-history --target qoder
+ot import-history --target kiro
+ot import-history --target all
+```
+
+查看 watcher 路径：
+
+```bash
+ot watch --target qoder
+ot watch --target kiro
+```
+
+v1 优先使用 native hook。`import-history` 和 `watch` 是兜底能力。
+
+### 11. AI Agent 推荐流程
+
+当你需要在一个新工作区启用 CLI：
+
+```bash
+command -v ot
+ot init --update-gitignore
+ot auth status
+ot install --target all
+ot --json doctor
+```
+
+只有用户明确要求自动记录 Agent 行为时，才执行：
+
+```bash
+ot install --target all --with-agent-hooks
+```
+
+然后优先使用高层命令：
+
+```bash
+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
+ot report draft --today
+```
+
+不要直接改 `.openturtle-cli/state.db`，除非用户明确要求底层排查。
+
+### 12. AI Agent 禁止事项
+
+- 不要写项目 `.openturtle/`
+- 不要覆盖 `openturtle-knowledge`
+- 不要覆盖 `openturtle-automations`
+- 不要覆盖旧 `openturtle-todo`
+- 不要删除用户已有 Agent 配置
+- 不要把 token 写入代码、README、commit 或日志
+- 不要让 hook 阻塞 Git commit 或 Agent tool call
+- 不要伪造 Codex hook trust state
+- 不要在会议 Knowledge 尚未发布时确认项目更新
+- 不要跳过 `meetings updates list` 直接批量确认会议草稿
+- 不要修改 Qoder/Kiro 私有未知格式文件；只写本文列出的配置面
+
+### 13. JSON 输出约定
+
+CLI 默认输出 JSON，便于 AI Agent 读取。
+
+成功示例：
+
+```json
+{
+  "initialized": true,
+  "project_dir": "/path/to/project/.openturtle-cli"
+}
+```
+
+错误会输出到 stderr，并使用非 0 退出码。传全局 `--json` 时，错误也是稳定 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。
+
+### 14. 开发验证
+
+在 `frontend` 目录执行：
+
+```bash
+pnpm --filter @openturtle/cli test
+pnpm --filter @openturtle/cli build
+```
+
+打包前检查 tarball 内容：
+
+```bash
+cd apps/cli
+npm pack --dry-run
+```
+
+期望包内只包含 `dist/`、`README.md` 和 `package.json` 等运行所需文件，不包含 `src/` 或 `test/`。
+
+### 15. npm 自动发布
+
+`.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` 配置影响。
+
+构建后 MCP smoke test：
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | node apps/cli/dist/index.js mcp serve
+```
+
+## 常见问题
+
+### 我没有安装 Desktop，可以用吗？
+
+可以。CLI 的目标就是让没有 Desktop 的用户也能使用 OpenTurtle。
+
+### 安装 hook 会不会影响我提交代码？
+
+不会。它只记录信息，记录失败也不会改变提交结果。
+
+### Qoder 和 Kiro 支持 hook 吗？
+
+支持。Qoder 使用 settings hook；Kiro 使用 hooks/agent 配置。
+
+### 为什么不用 `.openturtle/`？
+
+为了避免和 Desktop 等本地能力混在一起。CLI 项目状态只放 `.openturtle-cli/`。
+
+### `node:sqlite` warning 是什么？
+
+部分 Node 版本会提示内置 SQLite 仍是 experimental。这个 warning 不影响 CLI 测试和基本使用。