@openturtle/cli 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +7 -4
  2. package/dist/commands/collaboration.js +14 -1
  3. package/dist/installers/agents.js +5 -2
  4. package/package.json +1 -1
  5. package/skill/openturtle-cli/SKILL.md +34 -8
package/README.md CHANGED
@@ -58,13 +58,15 @@ ot meetings list --project <project-id>
58
58
  ot work summary --project <project-id>
59
59
  ot worklogs show <worklog-id>
60
60
  ot worklogs list --project <project-id> --to <iso-time> --scope team
61
- ot context get --project <project-id> --query "本周风险" --trace --include-candidates
61
+ ot context get --project <project-id> --query "本周风险"
62
62
  ot worklogs record --summary "完成联调" --type progress --todo <todo-id>
63
63
  ot report draft --today
64
64
  ```
65
65
 
66
66
  `ot install` 只安装 CLI 使用指引。Agent 直接执行 `ot ... --json`，不需要 MCP 或 Hook。
67
67
 
68
+ 普通项目综合问答优先使用一次聚合 `context get`，最多再做一次定向补查。日常回答不要使用 `--trace`、`--include-candidates`、`--help` 或全量对象列表；两次读取后仍缺信息时应明确标记“未召回”并停止。`trace` 只用于召回审计和故障诊断。
69
+
68
70
  ## 常用场景
69
71
 
70
72
  ### 看我的待办
@@ -102,7 +104,7 @@ ot knowledge local search "日报"
102
104
 
103
105
  ```bash
104
106
  ot knowledge search "日报" --project <project-id> --as-of 2026-07-27T07:28:32Z
105
- ot context get --project <project-id> --query "E1-X1" --snapshot <snapshot-id> --trace --include-candidates
107
+ ot context get --project <project-id> --query "上次回读验收还有什么缺口" --snapshot <snapshot-id>
106
108
  ```
107
109
 
108
110
  使用 `--as-of`、`--snapshot` 或任一排除参数时，聚合搜索只返回服务端云端结果，避免无版本边界的本地索引混入；这类参数不能与 `--local-only` 同时使用。
@@ -387,8 +389,9 @@ ot roster list --project <project-id>
387
389
  ot work summary --project <project-id>
388
390
  ot digest get --project <project-id> --window this_week
389
391
  ot context get --project <project-id> --query "本周风险" --section risk
390
- ot context get --project <project-id> --query "E1-X1" --trace --include-candidates
391
- ot context get --project <project-id> --query "E1-X1" --snapshot <snapshot-id> --trace
392
+ ot context get --project <project-id> --query "上次回读验收还有什么缺口" --snapshot <snapshot-id>
393
+ # 仅在诊断召回时使用：
394
+ ot context get --project <project-id> --query "上次回读验收还有什么缺口" --trace --include-candidates
392
395
  ot context item meeting <meeting-id> --project <project-id>
393
396
  ```
394
397
 
package/dist/commands/collaboration.js CHANGED
@@ -1,6 +1,18 @@
1
1
  import { ApiClient, listQuery } from '../core/api-client.js';
2
2
  import { collectOption, parseKeyValueOptions, readJsonBody } from '../core/input.js';
3
3
  import { addReadBoundaryOptions, addSnapshotPolicyOptions, buildReadBoundaryQuery, buildSnapshotExportBody, } from './read-boundary.js';
4
+ const PROJECT_ACTIVE_TODO_STATUSES = ['draft', 'pending', 'in_progress', 'pending_review', 'failed'];
5
+ function withProjectTodoSummary(project) {
6
+ const byStatus = project.todo_stats?.by_status;
7
+ const projectActiveTodoCount = byStatus
8
+ ? PROJECT_ACTIVE_TODO_STATUSES.reduce((total, status) => total + Number(byStatus[status] || 0), 0)
9
+ : null;
10
+ return {
11
+ ...project,
12
+ active_todo_count_scope: 'current_user',
13
+ project_active_todo_count: projectActiveTodoCount,
14
+ };
15
+ }
4
16
  export function createCollaborationCommands(client = new ApiClient()) {
5
17
  const mutate = async (method, path, body, dryRun = false) => {
6
18
  if (dryRun)
@@ -20,9 +32,10 @@ export function createCollaborationCommands(client = new ApiClient()) {
20
32
  const response = await client.get('/api/projects', {
21
33
  keyword: query,
22
34
  activated_only: false,
35
+ include_todo_stats: true,
23
36
  page_size: 100,
24
37
  });
25
- const items = Array.isArray(response) ? response : response.items || [];
38
+ const items = (Array.isArray(response) ? response : response.items || []).map((item) => withProjectTodoSummary(item));
26
39
  const exact = items.find((item) => item.id === query || String(item.name || '').toLowerCase() === query.toLowerCase());
27
40
  return {
28
41
  resolved: Boolean(exact),
package/dist/installers/agents.js CHANGED
@@ -25,7 +25,8 @@ export function installCursor(options) {
25
25
  '---',
26
26
  '',
27
27
  'Run OpenTurtle operations with the direct `ot ... --json` CLI. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
28
- 'Start with `command -v ot` and `ot --json doctor`; if authentication is missing, ask the user to run `ot auth login --web`.',
28
+ 'On first use in a new execution environment, run `command -v ot` and `ot --json doctor`; do not repeat these checks in the same task.',
29
+ 'For ordinary project synthesis, use OpenTurtle API data as the sole authority, start with one aggregated `ot context get` call using natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
29
30
  'Before a write, run the same command with `--dry-run` and inspect the request path and body.',
30
31
  'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
31
32
  '',
@@ -41,7 +42,8 @@ export function installKiro(options) {
41
42
  '# OpenTurtle CLI',
42
43
  '',
43
44
  'Run OpenTurtle operations with the direct `ot ... --json` CLI. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
44
- 'Start with `command -v ot` and `ot --json doctor`; if authentication is missing, ask the user to run `ot auth login --web`.',
45
+ 'On first use in a new execution environment, run `command -v ot` and `ot --json doctor`; do not repeat these checks in the same task.',
46
+ 'For ordinary project synthesis, use OpenTurtle API data as the sole authority, start with one aggregated `ot context get` call using natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
45
47
  'Before a write, run the same command with `--dry-run` and inspect the request path and body.',
46
48
  'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
47
49
  '',
@@ -135,6 +137,7 @@ function appendAgentsSnippet(workspace) {
135
137
  '',
136
138
  'Use the direct `ot ... --json` CLI for OpenTurtle projects, goals, todos, knowledge, meetings, and worklogs. Do not use an OpenTurtle MCP server or install OpenTurtle hooks.',
137
139
  'Run `ot --json doctor` when authentication or server reachability is uncertain, and use `--dry-run` before writes.',
140
+ 'For ordinary project synthesis, use OpenTurtle API data as the sole authority, use one aggregated `ot context get` call with natural business-language queries, and allow at most one targeted follow-up. Never prime the request with project-specific tracking codes. Do not inspect repository files, Git state, or local agent memory. Before answering, remove tracking keys from prose and source labels; keep only machine IDs in citation or audit fields. New object titles and summaries must use natural business language, with tracking keys stored separately.',
138
141
  'Todo quality: include source context, scope/environment, concrete steps, measurable acceptance criteria, and evidence. Ask one concise question when required information is unclear.',
139
142
  '',
140
143
  '<!-- /OPENTURTLE-CLI -->',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openturtle/cli",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "OpenTurtle collaboration, knowledge, meeting, and agent CLI",
5
5
  "keywords": [
6
6
  "openturtle",
package/skill/openturtle-cli/SKILL.md CHANGED
@@ -11,7 +11,7 @@ Desktop 会在隐藏系统上下文中注入已启用 Connector 的命令、能
11
11
 
12
12
  用户要求新增外部服务时，先准备符合 `schemaVersion: 1` 的 manifest，再调用 `openturtle-desktop` 的 `propose_connector`。该调用只提交待审批提案；用户必须在“扩展 > 连接器”批准，安装和写操作仍需单独确认。不得直接修改 Desktop 配置或 Connector 目录。
13
13
 
14
- 开始前运行：
14
+ 每个新执行环境首次使用前运行；当前任务已经验证过后不要重复：
15
15
 
16
16
  ```bash
17
17
  command -v ot
@@ -20,19 +20,44 @@ ot --json doctor
20
20
 
21
21
  缺少登录态时让用户运行 `ot auth login --web`，不要索取或输出 token。Desktop 内置 Agent 会自动复用 Desktop 当前登录态、团队和项目上下文；独立终端使用 CLI 自己的登录配置。
22
22
 
23
+ 只读 OpenTurtle 业务问题以 OpenTurtle API 返回的 Project Context 和业务对象为唯一权威来源，不读取仓库源码、`CLAUDE.md`、Git 状态、其他本地项目文件或 Codex/Claude 的历史 Memory。只有用户明确要求结合本地历史，或询问代码并要求修改时，才进入对应本地资料流程。Skill 已给出可用命令时不要预先调用 `--help`，只在命令真实报参数错误后查询一次对应帮助。
24
+
25
+ ## 聚合优先与读取预算
26
+
27
+ 普通用户询问项目现状、决策、工作包、会议结论、风险或下一步时，默认测试的是服务端 Project Context 聚合能力：
28
+
29
+ 1. 已知项目和语料边界时，直接执行一次 `context get`。把用户问题拆成 2-6 个自然业务短句，用可重复的 `--query` 一次提交；默认 `--limit 20`，不要先用更大 limit 再缩小重跑。不得把内部实验编号、工作包代号或机器 ID 当成用户必须知道的检索口令，也不要在系统提示或示例中枚举当前项目的实际代号。内部追踪键只放在来源或审计字段；标题包含追踪键时，正文略去该前缀并使用自然业务名称。
30
+ 2. 普通综合问答最多执行 2 次 OpenTurtle 业务读取。第二次只能是一次定向 `context get` 或一个已知 ID 的 `show`，不能再展开全量 `goals/todos/worklogs/knowledge/meetings list` 查询链。
31
+ 3. 两次读取后仍缺信息时，明确写“未召回”及缺失项并停止。不要为了让答案看起来完整而继续搜索。
32
+ 4. 普通回答禁止使用 `--trace`、`--include-candidates`、全量对象列表和全量 WorkLog。`trace` 只用于用户明确要求审计召回或诊断缺失；一次诊断只运行一个 trace 查询。
33
+ 5. 机器 ID 在命令和来源中必须完整复制，不得截断、缩写或凭记忆重写。聚合结果已经覆盖用户问题时立即作答。
34
+ 6. 普通项目综合问答以 60 秒内完成为目标。项目解析完成后优先只做一次 Context 读取；只有缺失事实会实质改变答案时才做第二次定向读取，不为扩写背景或增加篇幅补查。
35
+ 7. 作答前做一次展示层检查：除来源中的机器 ID 外，标题、段落、小标题、列表和来源标签都不得出现仅用于追踪的编号或代号。原始标题或摘要带追踪前缀时，按对象类型和业务内容改述；无法确定自然名称时使用对象类型加内容摘要，不得原样复制追踪键。
36
+
37
+ ```bash
38
+ ot context get --project <id> --snapshot <snapshot-id> \
39
+ --query "当前目标和成功标准" \
40
+ --query "正在推进哪些工作，目前分别是什么状态" \
41
+ --query "最近一次会议讨论了什么，哪些问题尚未决定" \
42
+ --query "当前正式决策和验证路径" \
43
+ --query "最近验收结果和遗留缺口" \
44
+ --limit 20
45
+ ```
46
+
23
47
  ## 读取流程
24
48
 
25
- 1. 用 `ot projects list` 或 `ot projects resolve <query>` 定位项目。
26
- 2. 用 `ot roster list --project <id>` 解析成员；先匹配 canonical `display_name`，再参考 aliases 和项目角色，重名或无法唯一匹配时询问用户。
27
- 3. 用 `ot context get --project <id> --query <term>` 获取项目上下文；复杂问题拆成少量明确查询词。需要审计召回时加 `--trace --include-candidates`。
28
- 4. 按对象读取：`ot work summary`、`ot goals list/show`、`ot todos list/show`、`ot knowledge list/show/search`、`ot knowledge local list/search/read`、`ot meetings list/show/transcript/minutes/participants`、`ot worklogs list/show`。
49
+ 1. 项目未知时优先用 `ot projects resolve <query>` 定位；已有项目 ID 或唯一的当前项目时不要再 list/resolve。
50
+ `active_todo_count` 是当前用户相关的活跃待办，项目整体进度使用 `project_active_todo_count` 和 `todo_stats`，不得把个人数字表述为项目总数。
51
+ 2. 只有问题涉及具体人员时才用 `ot roster list --project <id>` 解析成员；先匹配 canonical `display_name`，再参考 aliases 和项目角色，重名或无法唯一匹配时询问用户。
52
+ 3. 用一次 `ot context get --project <id> --query <term>` 获取项目上下文；复杂问题用同一命令的多个 `--query`，遵守上面的读取预算。
53
+ 4. 聚合结果缺少一个关键事实时，第二次读取可按已知对象使用 `ot goals/todos/knowledge/meetings/worklogs show`，或执行一次更精确的 Context 查询。对象 list/search 只用于用户明确要求浏览集合，不用于普通综合问答补全。
29
54
  5. 记录 Todo 执行进展时优先使用 `ot worklogs record --summary "..." --type progress --todo <todo-id>`，可同时传 `--project` / `--goal`，不要只把关联 ID 塞进 metadata。
30
55
  6. 高层命令缺失时才使用只读逃生口 `ot request get /api/...`。
31
56
 
32
57
  需要可重复语料边界时，优先让服务端执行，不要先全量读取再用 `jq` 猜边界：
33
58
 
34
59
  ```bash
35
- ot context get --project <id> --query <term> --as-of <iso> --exclude-tag evaluation-artifact --trace
60
+ ot context get --project <id> --query <term> --as-of <iso> --exclude-tag evaluation-artifact
36
61
  ot worklogs list --project <id> --snapshot <snapshot-id> --scope team
37
62
  ```
38
63
 
@@ -45,6 +70,7 @@ ot worklogs list --project <id> --snapshot <snapshot-id> --scope team
45
70
  - 创建目标、Todo、正式决策/风险、提交审核、审核通过/驳回、确认会议项目更新前，必须展示明确草稿和影响。
46
71
  - 项目归属只能来自用户明确选择，或受管 Goal/Meeting 唯一解析出的项目；无法唯一确定时停止写入并询问。
47
72
  - Knowledge 保存可长期复用的结论和完整会议纪要；短进展、决策、风险和产物引用写入 WorkLog。原始文件是 Knowledge 的来源材料，不是第二套知识系统。
73
+ - 新建或更新 Goal、Todo、WorkLog、Knowledge 和 Meeting Update 时，面向用户的 `title`、`summary`、正文和验收描述必须使用自然业务语言。需要内部追踪键时放入 metadata 或关系字段，不得把它作为标题前缀或要求用户在后续提问中使用。
48
74
 
49
75
  ## Todo 与 Goal
50
76
 
@@ -81,10 +107,10 @@ ot worklogs list --project <project-id> --window this_week --event-type progress
81
107
  ot projects snapshot export <project-id> --as-of <iso> --exclude-tag evaluation-artifact --dry-run
82
108
  ot projects snapshot list --project <project-id>
83
109
  ot projects snapshot show <snapshot-id>
84
- ot context get --project <project-id> --query <term> --snapshot <snapshot-id> --trace --include-candidates
110
+ ot context get --project <project-id> --query <term> --snapshot <snapshot-id>
85
111
  ```
86
112
 
87
- 快照建立后不可更新或删除。`trace` 返回候选数、选中/遗漏数、rank、score、匹配原因和截断信息；需要判断关系链稳定性时，应使用明确查询词并检查结构化关联理由，不能把一次召回当成稳定修复。
113
+ 快照建立后不可更新或删除。普通业务问答直接使用给定 snapshot ID，不要先 `show/list` 快照。只有服务端明确返回 snapshot 无效时才核对一次完整 ID 和快照列表。诊断召回时可给单个明确查询加 `--trace --include-candidates`；trace 返回候选数、选中/遗漏数、rank、score、匹配原因和截断信息，不能把一次召回当成稳定修复。
88
114
 
89
115
  ## Knowledge
90
116