# Meegle CLI Agent 使用教程 这份文档给 Agent、自动化脚本和 CI 使用。目标不是介绍所有命令，而是定义一套**低猜测、低回滚、可验证**的调用方式。 如果你是人类用户： - 日常使用优先看 [README.md](./README.md) - 踩坑说明优先看 [COMMUNITY-GUIDE.zh-CN.md](./COMMUNITY-GUIDE.zh-CN.md) 如果你是 Agent： - 默认按本文执行 - 默认使用结构化输出 - 默认先规划，再写入，再验证 ## 一句话原则 1. 写前先规划，不盲写。 2. 读命令默认 `--json`。 3. 变更追踪默认 `workitem history --json --view agent`。 4. 写命令成功后，优先信 CLI 的回读校验，不要只信接口返回 `ok`。 5. 不猜字段 key、不猜选项值、不猜角色标识，先查元数据。 ## 推荐运行环境 建议 Agent 运行前显式设置： ```bash export MEEGLE_AGENT=1 export MEEGLE_OUTPUT=json ``` 为什么： - `MEEGLE_AGENT=1` 会把 CLI 强制视为非交互环境，防止误触发交互确认 - `MEEGLE_OUTPUT=json` 能让所有读命令默认返回 JSON，避免文本解析 ## Agent 标准链路 ### 1. 建立身份 先确认当前 profile 可用： ```bash meegle --profile auth status --json ``` 最少检查这些字段： - `ok` - `profile` - `baseURL` - `tokenType` 如果要动态发现空间和类型： ```bash meegle --profile space list --json meegle --profile space types --project-key --json ``` ### 2. 写前统一规划 默认先跑： ```bash meegle --profile agent plan-write \ --project-key \ --type-key \ --id \ --json ``` 如果目标是子任务： ```bash meegle --profile agent plan-write \ --project-key \ --type-key \ --id \ --task-id \ --json ``` 跨时区语义必须显式传： ```bash --timezone America/Los_Angeles ``` Agent 必须优先读取： - `kind` - `can_proceed` - `reason` - `resolution` - `preflight.required_info` - `preflight.meta_fields` - `preflight.suggested_commands` - `time_context` 决策规则： - `can_proceed = true`：执行 `suggested_commands` 里最接近目标的写命令 - `can_proceed = false`：不要盲写，先补齐缺失上下文 ### 3. 写后查操作记录 如果 Agent 需要确认“谁在什么时候做了什么”，不要直接消费原始操作记录，默认用： ```bash meegle --profile workitem history \ --project-key \ --id \ --json \ --view agent ``` 这个视图返回的是稳定摘要，不要求 Agent 自己解析 `record_contents`。 ## `workitem history --view agent` 的稳定契约 推荐参数： ```bash meegle --profile workitem history \ --project-key \ --id \ --all \ --json \ --view agent ``` 返回重点字段： - 顶层： - `returned` - `has_more` - `next_cursor` - `unresolved_user_keys` - `items[*]`： - `time` - `time_text` - `work_item_id` - `action` - `action_text` - `module` - `module_text` - `operator_key` - `operator_name` - `operator_display_name` - `operator_type` - `source_type` - `source` - `objects` - `summary` 示例： ```json { "time": 1776006989146, "time_text": "2026/04/12 23:16:29", "work_item_id": 11483392, "action": "modify", "action_text": "修改", "module": "work_item_mod", "module_text": "工作项", "operator_key": "7613465676488904412", "operator_name": "LI YUXUAN", "operator_display_name": "LI YUXUAN（liyuxuan.uibe）", "operator_type": "user", "source_type": "plugin", "source": "MII_AB9273C26C7CB487", "objects": [ { "type": "comment", "id": "7627884700438220511", "label": "评论 7627884700438220511" } ], "summary": "修改：评论 7627884700438220511: old -> new" } ``` Agent 消费建议： - 优先用 `summary` 生成汇总 - 用 `objects[*].type` 判断变更对象 - 用 `operator_display_name` 直接展示给人 - 只有在 `unresolved_user_keys` 非空时，才退回 `operator_key` ## `history` 的真实使用建议 ### 1. 按字段看变更 ```bash meegle --profile workitem history \ --project-key \ --id \ --field priority \ --json \ --view agent ``` 适合： - 判断优先级是谁改的 - 判断标题、负责人、状态字段是否被改过 ### 2. 按时间范围追查 ```bash meegle --profile workitem history \ --project-key \ --id \ --since 2026-04-01 \ --until 2026-04-03 \ --json \ --view agent ``` 注意： - 裸日期会按有效时区解释 - `--end 2026-04-03` 等价于当天 `23:59:59.999` ### 3. 按操作者追查 ```bash meegle --profile workitem history \ --project-key \ --id \ --actor \ --json \ --view agent ``` ### 4. 按模块追查 ```bash meegle --profile workitem history \ --project-key \ --id \ --module field \ --json \ --view agent ``` 模块语义： - `workitem` -> `work_item_mod` - `workflow` -> `node_mod` - `subtask` -> `sub_task_mod` - `field` -> `field_mod` - `member` -> `role_and_user_mod` - `baseline` -> `baseline_mod` 重要说明： - 评论修改在真实环境里可能落到 `work_item_mod` - 所以“只看评论”不能只靠 `module` - 应该同时看 `objects[*].type == "comment"` ## 写命令选择 ### 工作项 更新工作项字段： ```bash meegle --profile --yes workitem update \ --project-key \ --type-key \ --id \ --field field_key=value \ --json ``` ### 节点 只更新节点信息： ```bash meegle --profile --yes workflow node-update \ --project-key \ --type-key \ --id \ --node-id \ --json ``` 完成 / 回滚节点并顺带写字段： ```bash meegle --profile --yes workflow node-operate \ --project-key \ --type-key \ --id \ --node-id \ --action confirm \ --json ``` ### 子任务 只更新子任务： ```bash meegle --profile --yes subtask update \ --project-key \ --type-key \ --id \ --node-id \ --task-id \ --json ``` 完成 / 回滚子任务并顺带写字段： ```bash meegle --profile --yes subtask operate \ --project-key \ --type-key \ --id \ --node-id \ --task-id \ --action confirm \ --json ``` ## 字段与负责人规则 1. 普通字段统一用 `--field`。 2. 节点交付物走 `--field`。 3. 子任务交付物走 `--deliverable`。 4. 角色负责人走 `--role-assignee ROLE=USER1,USER2`。 5. 非角色负责人走 `--assignee` 或 `--node-owners`。 6. 不要猜字段 option value，先查 `workitem meta`。 ## 时间规则 1. `--timezone` 优先级最高。 2. 未传 `--timezone` 时，回退到 profile 的 `defaultTimeZone`。 3. 两者都没有，才使用本机时区。 4. 时间特别敏感时，优先传完整 ISO 时间。 ## 回读校验 CLI 会对关键写操作做回读校验。Agent 应把这视为最终结果，而不是只看接口是否返回成功。 当前会自动校验的典型字段： - 节点：`node_owners`、`role_assignee`、`node_schedule` - 子任务：`note`、`assignee`、`role_assignee`、`schedule` 如果接口返回成功但回读不一致，CLI 会返回： - `error.code = WRITE_VERIFICATION_FAILED` Agent 必须视为失败，不要继续串联下游写操作。 ## 已知限制 ### 1. 操作记录不是强实时 真实环境里 `workitem history` 可能存在短暂异步落库。 现状： - CLI 已对“首个空页”做有限次自动重试 - 但仍不能承诺写后瞬时可见 Agent 规则： 1. 查询为空不等于后端没有记录 2. 如果本次任务高度依赖操作记录，允许延迟再查一次 3. 不要把“空记录”直接当成写入失败证据 ### 2. 评论记录的模块归类 真实环境里评论修改可能表现为： - `module = work_item_mod` - `objects[*].type = comment` 所以： - 判断是否为评论变更时，优先看 `objects[*].type` - 不要只靠 `module` ### 3. `work_item_type_key` 可能为空 真实返回里 `work_item_type_key` 可能是空字符串。 所以： - 不要依赖它做主过滤条件 - 过滤优先使用 `project_key + work_item_id + action/module/object` ### 4. 子任务备注清空 后端不会可靠清空子任务备注。以下请求会被 CLI 直接拒绝： - `--note ''` - `{"note": null}` 返回： - `error.code = UNSUPPORTED_OPERATION` ## 推荐恢复策略 ### `INVALID_PARAMETER` 按这个顺序恢复： 1. `agent plan-write` 2. `workflow preflight` 或 `subtask preflight` 3. `workitem meta` 4. 使用真实字段结构重新发写请求 ### `WRITE_VERIFICATION_FAILED` 1. 立即停止后续联动写入 2. 把回读差异原样返回 3. 优先建议人工复核 ### `UNSUPPORTED_OPERATION` 1. 不重试 2. 不降级猜值 3. 返回明确替代动作 ## Agent 最佳实践 1. 默认总是先跑 `agent plan-write` 2. 默认总是加 `--json` 3. 操作记录默认总是加 `--view agent` 4. 跨时区总是显式传 `--timezone` 5. 不要盲猜字段 option value 6. 不要只信 `{"ok": true}` 7. 对不可可靠执行的动作直接停，不要连续重试