# Changelog

## 0.3.0

### Added

- 新增 [AGENT-OPS.zh-CN.md](./AGENT-OPS.zh-CN.md)，系统化说明 Agent 的鉴权、规划、写入、历史追踪、错误恢复与已知限制。
- `workitem history` 新增 `--view agent`，返回稳定摘要结构：
  - `operator_name`
  - `operator_display_name`
  - `objects`
  - `summary`
  - `unresolved_user_keys`

### Improved

- `workitem history` 默认终端输出改为优先展示操作者姓名，不再把裸 `user_key` 作为主展示内容。
- `workitem history` 支持把评论变更归一化为 `objects[*].type = comment`，Agent 不再需要从原始 `record_contents` 猜测对象类型。
- 发布包将显式包含 `AGENT-OPS.zh-CN.md`，安装后文档与 README 引导保持一致。

### Fixed

- 修复真实环境里操作记录首个空页会误判“没有记录”的问题；现在会对首个空页做有限次自动重试。
- 修复 `create/delete` 这类空数组变更在 Agent 摘要里被渲染成 `[空] -> [空]` 的低质量输出。

### Verified

- 本地回归：`npm test` 通过（41/41）。
- 真实环境验证通过：
  - `workitem history --json --view agent`
  - 操作者 `user_key -> 人名` 解析
  - 评论修改记录摘要
  - 默认终端输出的人名展示

## 0.2.1

### Fixed

- 修复 `--json --yes` 写操作仍向 `stderr` 输出风险预览的问题。现在机器模式下的写命令只输出结果本身，不再混入说明性文本。

### Improved

- `workitem create --json --yes` 这类命令的输出契约已收口为稳定的机器输出，便于脚本、Agent 和 CI 直接消费。

### Verified

- 本地回归：`npm test` 通过（38/38）。
- 发布包真实验证通过：
  - 全局安装 `meegle-cli@0.2.1`
  - `workitem create --json --yes` 的 `stdout` 仅输出工作项 ID，`stderr` 为空
  - `workitem remove --json --yes` 的 `stdout` 仅输出 JSON 结果，`stderr` 为空

## 0.2.0

### Added

- 新增 `agent plan-write`，统一规划 `workitem` / `node` / `subtask` 写操作，返回资源类型、阻塞项、建议命令与时区上下文。
- 新增 `workflow preflight` / `subtask preflight` 的 `time_context` 输出，方便 Agent 在写前确认当前时间解释语义。
- 新增 profile 级 `defaultTimeZone`，支持在 `auth init` 阶段固化默认 IANA 时区。

### Improved

- 所有关键写命令支持 `--timezone`，无时区日期/时间输入会按显式时区、profile 默认时区或本机时区依次解释。
- 节点 / 子任务写操作增加写后回读校验，覆盖负责人、角色负责人、备注、估分和排期。
- `suggested_commands` 会自动继承有效时区，降低 Agent 拼接命令时丢失时间语义的概率。
- `preflight` / `agent plan-write` 返回更完整的字段元数据，包含选项、默认值与关系信息，减少 Agent 额外补打一条 `workitem meta` 的需求。

### Fixed

- 修复 `YYYY-MM-DD` 曾被按 UTC 解释的问题，现已改为按有效时区解释当地日界线。
- 修复“估分 / 排期真实写入成功，但本地回读误判失败”的问题。
- 对“清空子任务备注”这种后端会静默忽略的写入，CLI 现在会直接返回 `UNSUPPORTED_OPERATION`，不再制造假成功。

### Verified

- 本地回归：`npm run build:all`、`node --test ./dist/tests/field-parser.test.js ./dist/tests/error-handler.test.js`、`node --test ./dist/tests/e2e-cli.test.js` 通过。
- 真实测试空间验证通过：
  - `workflow preflight`
  - `subtask preflight`
  - `agent plan-write`
  - 节点角色负责人写入与恢复
  - 节点估分 / 排期写入与恢复
  - 子任务估分 / 排期写入与恢复
  - `America/Los_Angeles` 显式时区写入
  - profile 默认时区透出到真实 `preflight` 输出

## 0.1.10

### Fixed

- 收紧 `--field` 语法，明确拒绝 `field_key[]=value`，统一要求数组字段写成 `field_key=[...]`。
- 修复关联字段快捷写入可能“返回 ok 但值未落库”的问题。CLI 现在会在必要时自动查询 `workitem meta` 并补齐 `field_type_key`。
- 修正 `INVALID_PARAMETER` 等场景下的 `suggested_command`，现在只输出命令骨架，例如 `meegle workitem update --help`，不再把 flag 值和参数值错误拼进去。

### Improved

- 文档和 Skill 明确区分两层能力：
  - `config relation ...` 管关系定义
  - `workitem update --field ...` 管实例关联写入
- 关联字段示例统一强调：
  - 传实例 ID
  - 多值写成 `field_key=[1,2]`
  - 不传显示名称

### Verified

- 本地回归：`npm test` 通过（20/20）
- 真实租户 `hcgm44` 验证通过：
  - `config relation` 增改删成功
  - `issue -> story` 关联字段 `_field_linked_story=<storyId>` 快捷写入成功并可回读