chatcrystal-task-writeback

ChatCrystal 任务回写

有意义的工作完成后使用此技能。让 ChatCrystal Core 决定是跳过、合并还是创建记忆。

工作流

1. 仅在实质性工作完成且产出了可复用的知识后触发。
2. 合适的候选内容包括：
   • 持久有效的修复
   • 有意义的易错点
   • 可复用的模式
   • 明确的工程决策

质量门禁预检

调用 write_task_memory 前，确认候选内容是经验资产，而非工作日志。

以下情况不要调用 write_task_memory：

• 总结只说明了改动内容，没有解释其重要性。
• 没有明确的问题、决策、易错点、解决方案或可复用的模式。
• 任务没有为未来工作带来持久有效的经验。

根据 memory.outcome_type，必需字段如下：

• fix：包含 root_cause 或 resolution。
• pitfall：包含 pitfalls，以及 resolution 或 reusable_patterns。
• decision：包含 decisions。
• pattern：包含 reusable_patterns。

将 memory.summary 写成持久有效的经验结论，而非“我做了 X”。

自动回写必须包含 source_run_key；没有该字段时，应输出结构化候选内容供之后保存，而不是悄悄写入手动记忆。

3. 如果 write_task_memory 可用，且运行环境有稳定的运行或会话密钥，则调用该工具并传入：
   • mode: "auto"
   • source_run_key：稳定的运行或会话密钥
   • task.goal、task.task_kind、task.project_dir、task.cwd、task.branch
   • 已知时传入 task.source_agent
   • memory.summary：简洁且持久有效，不要过于随意
   • memory.outcome_type：pitfall、fix、pattern、decision 之一
   • 相关时传入 memory.root_cause、memory.resolution、memory.error_signatures、memory.files_touched、memory.tags
4. 仅在明确的手动保存流程中使用 mode: "manual"，绝不可将其作为自动回写的静默后备方式。
5. 默认使用项目级知识。仅对明确跨项目的知识使用全局范围，且只能用于明确的手动保存流程。
6. 准确报告持久化结果：
   • created
   • merged
   • skipped

MCP 输入示例

在任务完成且有稳定运行密钥后调用 write_task_memory 时，使用以下格式：

{
  "mode": "auto",
  "source_run_key": "agent-session-or-run-id",
  "scope": "project",
  "task": {
    "goal": "Fix MCP recall schema validation",
    "task_kind": "debug",
    "project_dir": "/path/to/project",
    "cwd": "/path/to/project",
    "branch": "fix/mcp-recall-schema",
    "files_touched": [
      "server/src/services/memory/schemas.ts",
      "server/src/cli/mcp/server.ts"
    ],
    "error_signatures": [
      "invalid_type",
      "recall_for_task schema mismatch"
    ],
    "source_agent": "codex"
  },
  "memory": {
    "summary": "MCP tool schemas must stay aligned with memory service request shapes; mismatches surface as validation failures before tool execution.",
    "outcome_type": "fix",
    "root_cause": "The MCP tool input shape diverged from the service schema.",
    "resolution": "Reused the shared request shape in the MCP server registration.",
    "files_touched": [
      "server/src/services/memory/schemas.ts",
      "server/src/cli/mcp/server.ts"
    ],
    "tags": [
      "mcp",
      "memory-loop",
      "schema"
    ]
  }
}

完整模式

完整模式需要 ChatCrystal Core，以及对 write_task_memory 的 MCP 访问权限。

• 不要在技能中重新实现跳过或合并逻辑。
• 相信 Core 会决定是跳过、合并还是创建记忆。
• 如果工具报告 skipped，保留任务结果，但不要强行持久化。

降级模式

如果 ChatCrystal Core 或 MCP 工具不可用，或者自动回写时没有稳定的运行密钥：

• 不要声称记忆已保存。
• 在回复中输出结构化记忆候选内容，供之后保存。
• 候选内容应符合 write_task_memory.memory 负载的格式，以便之后复用。
• 不要指示运行环境在技能流程中自动安装 ChatCrystal Core。