write-report

write-report

编写命名和存放位置均正确的任务报告，并将其发布到 Quest 仪表板。封装了 CONVENTIONS.md 中的完整样板内容，避免 Agent 复制粘贴（或遗漏）。

适用场景

• 每项任务结束时编写任务报告
• 编写 rollcall 团队报告时
• 编写 speckit、deps、review 或 crew-runner 报告时
• 分派扇出批次并编写主管清单时

不适用场景

• 在 crew/*/ 子目录中——所有报告都应放在仓库根目录的 reports/
• 为其他团队编写报告时——每个 Agent 都应编写自己的报告

调用示例

# Standard mission report
/write-report --group crew-runner --id "fellowship-dev-navvi-42" --type crew-runner

# Rollcall team report
/write-report --group rollcall --id lexgo --type rollcall

# Fan-out manifest (written at dispatch time by supervisor)
/write-report --manifest --group rollcall --jobs "lexgo:pending,tooling:pending,navvi:pending"

工作流

步骤 1：确定报告目录

始终从 Git 仓库根目录确定路径——绝不要硬编码或使用 crew/*/：

REPORT_DIR="$(git rev-parse --show-toplevel)/reports"

如果 git rev-parse 失败，则说明你不在 Git 仓库中。切换到正确的项目根目录后重试。

步骤 2：生成文件名

所有时间戳均使用 UTC：

TIMESTAMP=$(date -u +"%Y%m%d-%H%M")

文件名格式：

报告类型	文件名
标准（speckit、deps、review、crew-runner）	{TIMESTAMP}_{group}_{id}.md
Rollcall 团队	{TIMESTAMP}_rollcall_{team}.md
Rollcall 汇总	{TIMESTAMP}_rollcall_assembly.md
扇出清单	{TIMESTAMP}_{group}_manifest.json

示例：

20260413-1100_rollcall_lexgo.md
20260413-1115_crew-runner_fellowship-dev-navvi-42.md
20260413-1100_rollcall_manifest.json

步骤 3：写入文件

对于 Markdown 报告——如果有 Write 工具，则使用该工具；否则改用 Bash：

REPORT_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_${ID}.md"

将完整报告内容写入该路径。如果 Write 工具不在你的 allowed-tools 中（例如 CEO/CTO 角色），则改用 Bash：

cat > "$REPORT_PATH" << 'REPORT_EOF'
[report content here]
REPORT_EOF

对于扇出清单（--manifest 标志）：

MANIFEST_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_manifest.json"

必需的 JSON 结构（所有字段均为必填项）：

{
  "group_id": "{group}-{YYYYMMDD}-{HHMM}",
  "origin_job": "~/.local/share/pylot/missions/done/{job-file}.job",
  "jobs": {
    "job-id-1": "pending",
    "job-id-2": "pending"
  },
  "created_at": "2026-04-13T11:00:00Z"
}

解析 --jobs 参数（格式："id1:state1,id2:state2,..."）：

python3 -c "
import json, sys
jobs_str = sys.argv[1]
jobs = {}
for pair in jobs_str.split(','):
    job_id, state = pair.strip().split(':')
    jobs[job_id.strip()] = state.strip()
manifest = {
    'group_id': sys.argv[2],
    'origin_job': sys.argv[3] if len(sys.argv) > 3 else 'unknown',
    'jobs': jobs,
    'created_at': sys.argv[4]
}
print(json.dumps(manifest, indent=2))
" "$JOBS_ARG" "${GROUP}-${YYYYMMDD}-${HHMM}" "${ORIGIN_JOB:-unknown}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MANIFEST_PATH"

任务状态： pending · done · failed

步骤 4：发布到 Quest DB

始终尝试发布——失败时静默跳过。清单不会发布，只发布 .md 报告：

QUEST_TOKEN=$(grep '^QUEST_TOKEN=' /home/ubuntu/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)
curl -s -X POST "http://127.0.0.1:4242/api/event" \
  -H "Authorization: Bearer $QUEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import json
content = open('$REPORT_PATH').read()
print(json.dumps({
  'source': 'commander',
  'type': 'commander.report',
  'title': '$REPORT_TITLE',
  'meta': {'content': content, 'report_type': '$GROUP'}
}))
")" 2>/dev/null || true

步骤 5：提交并推送

cd "$(git rev-parse --show-toplevel)"
git add reports/
git commit -m "report: ${GROUP} ${ID}"
git push

错误处理

git rev-parse 失败——不在 Git 仓库中。调用前切换到正确的项目根目录。

Quest 无法访问——离线或 Pod 环境中可能出现此情况。|| true 守卫会处理这种情况。不要重试。

--jobs 解析错误——任务字符串格式错误。正确格式为："id1:state1,id2:state2"。每一对中必须恰好包含一个 : 分隔符。

文件已存在——Write 工具会覆盖文件。如果在同一分钟内写入多份报告，请在 ID 后追加后缀。

关键规则

• 绝不要写入 crew/*/——使用 git rev-parse --show-toplevel 确定路径
• 所有时间戳均使用 UTC——始终使用 date -u
• 清单不会发布到 Quest——只发布 .md 文件
• 工作者应编写自己的报告——绝不要编写其他团队的报告
• 跳过 Quest 时必须保持静默——|| true 是必需的，不可省略