write-report

用途

write-report 用于撰写命名正确、位置正确的任务报告，并提交到 Quest 仪表盘（网关数据库）。它把 CONVENTIONS.md 中的全部样板逻辑封装起来，避免智能体复制粘贴或遗忘相关规范。

主要能力

生成符合约定的报告文件名与存放路径。
支持多种报告类型：标准任务报告（speckit、deps、review、crew-runner）、点名团队报告、点名汇总、以及扇出清单（manifest）。
可写入 Markdown 报告，也可写入 JSON 格式的扇出清单。
将 .md 报告提交到 Quest 数据库。
完成后提交并推送 git。

使用方式

调用示例

# 标准任务报告
/write-report --group crew-runner --id "fellowship-dev-navvi-42" --type crew-runner

# 点名团队报告
/write-report --group rollcall --id lexgo --type rollcall

# 扇出清单（由 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 仓库中。请 cd 到正确的项目根目录后重试。

第 2 步：生成文件名

所有时间戳均为 UTC：

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

文件名模式：

报告类型	文件名
标准（speckit、deps、review、crew-runner）	{TIMESTAMP}{group}{id}.md
点名团队	{TIMESTAMP}rollcall{team}.md
点名汇总	{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 仓库中。调用前先 cd 到正确的项目根目录。
Quest 不可达——在离线/pod 环境中属预期情况。|| true 守卫会处理。不要重试。
--jobs 解析错误——jobs 字符串格式错误。预期格式："id1:state1,id2:state2"。每个键值对需要且仅需要一个 : 分隔符。
文件已存在——Write 工具会覆盖。如果同一分钟内写入多份报告，请在 ID 后追加后缀。

关键规则

绝不写入 crew/*/ —— 通过 git rev-parse --show-toplevel 解析路径
所有时间戳均为 UTC —— 始终使用 date -u
清单不会被提交到 Quest —— 只有 .md 文件会被提交
工作者撰写自己的报告 —— 绝不代其他团队撰写报告
Quest 跳过必须静默 —— || true 是必需的，而非可选

不适用场景

在 crew/*/ 子目录内——所有报告都写入仓库根目录的 reports/
代其他团队撰写报告——每个智能体撰写自己的报告

限制

关于该技能的收费、价格、平台兼容性等具体信息，资料中暂未提供。