Xhuk/skillgram 问题报告

skillgram 问题报告 是做什么的？

激活条件

当以下任一情况为真时使用此技能：

• skillgram 输出 ok:false，以退出码 1/2 退出，崩溃，或输出与磁盘状态矛盾（registered 但 harness 配置中无对应条目、链接指向无效位置、挂载报告零技能而 manifest 中却有技能）。
• 代理需要某项能力，而 skillgram missing "<query>" 返回 found:false。
• 在按文档重启后，安装或注册未在 harness 中生效。

不适用于：“如何运行 X”（请阅读 INSTALL.md），或没有可观察缺口的特性想法。

严格规则

1. 错误绝不作为技能提交。切勿运行 propose 来掩盖故障行为。
2. 缺口绝不作为错误提交。中心没有某项能力仅代表一个请求。
3. 不得捏造证据：每个退出码、路径和 JSON 行必须来自你刚刚运行的命令。
4. 粘贴前需脱敏：令牌、密码、私有主机、客户名称。保留结构，更改值。
5. 绝不要通过手动编辑 harness 配置文件（config.toml、config.yaml、.claude.json、.cursor/mcp.json）来“修复” skillgram。这会隐藏 bug。
6. 在声称成功之前重新检查配置：<harness> mcp get skillgram（或 mcp list）和 skillgram status。退出码不能作为证明。

决策门

观察结果	渠道
ok:false、非零退出码、错误链接、输出中的谎言、崩溃	bug → bug_report.yml
针对你实际需要的能力返回 found:false	技能请求 → skill_request.yml
缺失的是 skillgram 的命令、标志或行为，而非技能	bug（在标题中注明“特性”）
在另一台机器或 harness 上正常工作	作为证据记录；它不是修复
不确定	收集两方面证据，让用户选择渠道

执行步骤

1. 重现一次，保留确切的命令行。使用 CLI（skillgram <command> --json，或当未安装时使用 python <repo>/skillgram.py <command> --json）并记录退出码（PowerShell 上为 $LASTEXITCODE，POSIX 上为 $?）。
2. 捕获环境：
   • skillgram status --json
   • skillgram doctor --json（只读；删除你不想公开的路径）
   • 操作系统、Python 版本、skillgram 版本、harness 以及你使用的启动器（当 PATH 上的不是正确版本时，使用 SKILLGRAM_MCP_CLI_<HARNESS>）。
3. 对于任何注册声明，在声称成功的命令之后捕获 <harness> mcp get skillgram（或 mcp list）。
4. 对于缺口，捕获 skillgram missing "<query>" --json 和 skillgram demand --limit 20（它会排名无人能回答的查询，以便 Issue 与需求日志对齐）。
5. 根据模板撰写 Issue，并在发布前向用户展示。使用 gh issue create --repo Xhuk/skillgram --template bug_report.yml（或当自行填写表单时使用 --body-file <file>）发布，或者将文本交给用户。

输出契约

回复确切包含：

• 渠道：bug 或 skill-request
• 证据：命令、退出码、一行 JSON
• 环境：操作系统 / Python / skillgram / harness / 启动器
• 期望结果：一句话，不做推测
• 处置方式：已发布（附 Issue URL）或作为文本留给用户