msdevflow 0.6.0

package/skill/msdevflow/references/setup-and-issue.md

@@ -0,0 +1,165 @@
+# Action `discover` 与 `issue`
+
+在显式 `action=discover`、`action=issue`，或未指定 action 的完整作者 E2E 启动时读取；显式 `action=create-issue` 只读取本文件的公共环境、仓库上下文和最小充分画像，模板和写入业务转到 [create-issue.md](create-issue.md)，不得执行本文件的发现、接取或重复实现核验。`discover` 全程只读并在候选报告后立即停止；`issue` 只接取和核验指定 Issue，达到 `verified` 后立即停止，不进入开发。
+
+显式 `action=issue` 必须提供 Issue URL 或编号。缺少目标时只做确认输入缺失所需的只读核验，随后返回 `blocked` 并建议先运行 `action=discover`；不得在本 action 内查询候选、让用户选择 Issue 或执行 `discover` 的业务。
+
+## Phase 0：环境和能力
+
+### CLI
+
+```bash
+<gitcode-command> version
+<gitcode-command> auth status --json
+git status --short --branch
+git remote -v
+```
+
+只展示 `username`、`logged_in`、`token_source` 和 Git protocol，不显示 Token。首次进入目标仓库或身份与用户预期不明确时，先让用户确认账号，再进行远端查询或写操作。账号确认问题必须同时展示已识别的账号和待查询 canonical 仓库范围；不得改为要求用户提供 Issue。认证失败时停止，引导用户先运行 `npx msdevflow setup`；如只需手动恢复认证，则在自己的终端运行 `<gitcode-command> auth login --web`。凭证由 GitCode CLI 自己管理，不在对话或 workflow 中接收 Token。
+
+使用所需命令前优先运行：
+
+```bash
+<gitcode-command> schema "<command>"
+```
+
+无 `schema` 时检查 `--help`。只探测当前 action 所需能力；`create-issue` 探测 issue create/view 和 UTF-8 安全写入能力，但不探测 issue list/prs 做查重；完整作者 E2E 至少探测 issue list/view/edit/comment、pr view/diff/create/comments/reply/merge 和仓库 CI 查询方式。CLI 缺失或能力不足时读取 [command-capabilities.md](command-capabilities.md)，停止当前 action 并提示用户运行独立 setup；setup 成功后恢复原 action，不在 workflow 内隐式安装依赖。
+
+### 无目标发现
+
+用户未提供 Issue、PR 或仓库时，不得立即索要 Issue。按以下顺序缩小范围：
+
+1. 检查当前目录是否为 Git 仓库；若不是，扫描直接子目录中的 Git 仓库。
+2. 读取 remotes，按以下证据识别 canonical 候选：明确命名的 `upstream`/`origin`、Fork 与上游关系、remote HEAD、仓库 URL 和本地说明。个人 Fork 只能作为 source 候选，除非没有任何上游证据。
+3. 合并指向同一 canonical 的重复工作树；临时、CI drill 或同仓多 clone 不得导致重复查询。
+4. 若唯一 canonical 可确定，继续账号确认和候选查询。
+5. 若存在多个可信 canonical，且都位于当前工作区并属于已授权范围，先展示账号和仓库清单，请用户确认查询这些仓库；不要要求用户先选择或提供 Issue。用户先前已明确授权该范围时可直接只读查询。
+6. 只有仓库身份无法从本地证据判断，或候选包含来源不明、非授权、数量异常的仓库时，才停止并询问范围。问题必须列出可验证的候选和歧义点。
+7. 对确认范围内每个 canonical 查询分配给当前账号的开放 Issue；若仓库没有匹配项，记录为空并继续其他仓库。
+8. 按“有界核验”处理初步候选，仅依据 Issue 元数据、评论和关联 PR 排除已有明确闭环证据、存在他人活跃实现或维护者明确取消的事项。没有明确闭环证据时默认列为待处理。
+9. 最终只列出仍需处理的候选，并附排除项及简短证据。没有候选时明确报告查询范围和排除结果。
+
+#### 有界核验
+
+候选发现只判断远端 Issue 是否有明确闭环证据，并限制单轮延迟和输出：
+
+1. **第一轮——元数据筛选**：只执行一次 `issue list`，从返回的 state、assignees、labels、updated_at 和 comments 数量建立候选表。`resolved` 标签或 closed 状态是明确闭环信号，但若评论显示标签已撤销、Issue 被重新打开或维护者要求继续开发，则不得排除。`stale` 只表示闲置，不能单独证明已解决。
+2. **第二轮——评论**：对候选执行 `issue view --comments --json`，每波最多 4 个独立并行调用。评论中维护者明确表示已解决、无需修改、无法复现后关闭、取消或转由其他 Issue 处理时排除；他人明确认领且仍活跃时排除。只有机器人欢迎语、`pending`/`triaged` 或没有结论时，默认保留为待处理。
+3. **第三轮——关联 PR**：只对前两轮仍无明确结论的候选逐项执行 `issue prs`，每波最多 4 个独立并行调用。已有 open 或 merged PR 能覆盖该 Issue 时排除，并记录 PR 号和状态；没有关联 PR 时默认保留为待处理。
+4. 发现阶段禁止 fetch、搜索仓库文件、扫描 Git 历史或枚举远端分支。即使怀疑默认分支已实现，只要 Issue 元数据、评论和关联 PR 没有明确证据，也列为待处理候选。用户选定候选后，Phase 2 再核验默认分支和重复实现，确认后才进入开发。
+5. CLI 支持单 Issue `issue prs` 时，发现阶段不得运行仓库级 `issue relations`；后者仅在 `issue prs` 缺失或恢复时需重建关系时使用，并设置最小充分的 state/limit。
+6. 禁止在一个 PowerShell/Bash 循环中串行查询多个 Issue，禁止把多个 Issue 的原始 JSON 拼成一个输出。候选超过 4 个时分波执行；每完成一波就给用户一句进度更新。约 90 秒仍未完成时，先报告已核验数量和剩余数量。
+7. 只保留决策所需字段。不要读取或转存附件，不要在主上下文展开重复机器人欢迎评论、图片正文或完整关系表；工具返回过大时改为逐项查询和字段投影。
+8. 发现期不做仓库画像。用户选定候选后、进入 `verified` 前再读取仓库规范、测试、CI、review 和机器人协议。目标路径已知且预计不超过 3 次 Read/Grep 时直接使用专用工具，不为画像启动 worktree agent。
+
+无目标发现全程只读。接取、评论、创建分支、push 或其他远端写操作仍须按执行模式单独确认。
+
+### 仓库上下文
+
+建立并展示：
+
+```text
+gitcode_command
+canonical_repository
+canonical_default_branch
+canonical_remote
+source_repository
+source_remote
+operation_target
+issue_number
+pr_number（如已有）
+```
+
+从 URL、Git remotes、remote HEAD 和 PR base 交叉验证。canonical 身份不等于写授权。
+
+### 仓库画像
+
+读取适用范围的 `AGENTS.md`、`CLAUDE.md`、`CONTRIBUTING*`、README、Issue/PR 模板、OWNERS/CODEOWNERS、CI、pre-commit 和测试配置。PR 模板必须来自 canonical repository 最新默认分支，不得从个人 Fork、当前工作分支或本地未提交文件读取。先检查贡献指南或仓库配置明确指定的路径，再依次检查：
+
+1. `.gitcode/PULL_REQUEST_TEMPLATE.md`；
+2. `.gitcode/PULL_REQUEST_TEMPLATE/*.md`；
+3. `.github/PULL_REQUEST_TEMPLATE.md`；
+4. `.github/PULL_REQUEST_TEMPLATE/*.md`；
+5. 仓库根目录或 `docs/` 下的 `PULL_REQUEST_TEMPLATE.md`。
+
+使用 canonical remote 默认分支树或等价的已验证远端内容确认模板版本。优先采用仓库明确指定的模板；同一优先级存在多个候选且无法根据名称、仓库规则或变更类型唯一选择时，展示候选路径并让用户确认，不得拼接多个模板或自行猜测。未找到模板时记录 `PR template: none`，`action=pr` 使用工作流默认正文结构。
+
+记录：
+
+- 默认分支、分支和 commit 规范；
+- Issue 接取与 PR 关联规则；
+- Fork/主仓开发模式；
+- 测试、构建、格式、安全和 UI 验证命令；
+- CI 触发、状态和日志来源；
+- review、approval、merge 门禁和合并方式；
+- 项目机器人协议。
+
+仓库规则优先，但不能覆盖安全硬停止点。
+
+## Phase 1：发现与接取
+
+显式 `action=issue` 直接读取输入中的 Issue URL/编号；缺少目标时按本文件入口规则返回 `blocked`。显式 `action=discover` 或未指定 action 的完整作者 E2E 尚无目标时，才对“无目标发现”确认出的每个 canonical 查询当前用户负责的开放 Issue：
+
+```bash
+<gitcode-command> issue list -R <canonical> --state open --assignee <username> --json
+<gitcode-command> issue view <issue> -R <canonical> --comments --json
+```
+
+参数以 schema 为准。必须先完成发现期的元数据、评论和关联 PR 核验，再把“仍需处理”的 Issue 展示给用户选择；发现期不核验默认分支代码，没有明确闭环证据时默认列为待处理候选，也不得擅自领取。若远端查询尚在等待账号或仓库范围确认，报告具体待确认项，不得退回要求用户提供 Issue。
+
+读取 assignee、维护者评论、标签、里程碑和贡献规范：
+
+- 已分配当前用户：记录 `claimed`；
+- 未分配且允许自领：展示目标和动作，确认后用 CLI 设置 assignee；
+- 无权限或规则不明：确认后留言表达接取意向，等待维护者确认；
+- 已由他人处理或存在活跃 PR：停止并说明冲突。
+
+不得覆盖他人 assignee。Agent 发布接取意向、闭环证据或其他 Issue 评论时，按 [state-and-safety.md](state-and-safety.md) 使用 UTF-8 安全通道并附加唯一尾签；仅修改 assignee 等非正文元数据时不追加。评论后先逐字回读完整正文和尾签；正文不一致、尾签缺失或重复时原地修复并阻断 assignee/state/close 等后续写操作，验证通过后才继续。任何接取写操作结果不确定时先查询，不重试。
+
+## Phase 2：远端事实核验
+
+### 发现期
+
+只读取：
+
+- Issue 状态、正文、评论、标签、负责人、里程碑；
+- 单 Issue 的关联 PR：`<gitcode-command> issue prs <issue> -R <canonical> --json`；
+- 其他关系项和维护者决策。
+
+Issue 元数据、评论或关联 PR 存在明确闭环证据时排除；否则默认列为待处理。发现期不读取 canonical 代码、不扫描 Git 历史和远端分支。
+
+### 用户选定 Issue 后
+
+在进入开发前补充核验：
+
+- canonical 默认分支最新代码；
+- 评论或关联 PR 指向的具体实现；
+- 有具体证据线索时的相同问题分支或 PR。
+
+验证问题仍存在或需求尚未实现。Issue 已关闭不等于已实现，必须检查关联 PR 和默认分支；开放 Issue 也不等于一定未实现。若已闭环，停止重复开发并给证据。
+
+## 完成输出
+
+无目标发现暂停供用户选择时：
+
+```text
+Account: <username>
+Queried canonical repositories: ...
+Actionable candidates: <canonical>#<number> — <summary and verification evidence>
+Excluded candidates: <canonical>#<number> — <closed-loop or duplication evidence>
+Blocker: none | details
+Next state: discovered — waiting for candidate selection
+Confirmation required: select one candidate; no remote write has occurred
+```
+
+目标已确定时：
+
+```text
+Issue: <canonical>#<number>
+Claim: confirmed | waiting | blocked
+Canonical/source/operation target: ...
+Default branch: ...
+Existing implementation/PR: none | details
+Repository gates: summary
+Next state: verified | blocked
+```

package/skill/msdevflow/references/state-and-safety.md

@@ -0,0 +1,164 @@
+# 状态、授权与安全契约
+
+## 仓库上下文
+
+每次运行维护以下事实：
+
+```yaml
+run_id: <scope>-<yyyymmdd>-<short-id>
+mode: guided | autonomous
+ci_mode: guided | autonomous-ci
+gitcode_command: gitcode | gitcode-npm
+canonical_repository: owner/repo
+canonical_default_branch: branch
+source_repository: owner/repo-or-null
+source_remote: remote-name-or-null
+operation_target: owner/repo
+issue_number: number-or-null
+pr_number: number-or-null
+work_branch: branch-or-null
+head_sha: sha-or-na
+review_head_sha: sha-or-null
+requested_action: discover | create-issue | issue | develop | pr | ci | openlibing-auth | feedback | code-review | merge | e2e
+last_completed_state: state
+```
+
+这些字段来自远端和本地探测，不能靠猜。`run_id` 的 `<scope>` 使用 Issue、PR、action 或 `e2e` 的稳定小写标识；无对应事实的 source、Issue、PR、branch 或 head 字段保持 `null`/`na`。不要把 Token 或本地绝对路径写入状态记录。
+
+## GitCode 远端文本 UTF-8 传输
+
+本节适用于 Agent 创建或修改的 PR/Issue 标题、Issue/PR 正文、Issue/PR 评论、discussion 回复、CI 修复说明、合入协议说明和其他人类可读远端文本。正文类文本先生成包含尾签的最终内容，再一次性安全传输；不要先发正文再补尾签。标题等非正文元数据不追加尾签，但非 ASCII 内容仍必须使用安全通道并在写后逐字回读。
+
+### 首选通道
+
+1. 优先使用命令的 `--body-file`、`--comment-file` 或等价文件参数。
+2. 正文文件必须显式写为 UTF-8；Windows PowerShell 5.1 使用 UTF-8 **无 BOM**，不得依赖 `Out-File`、`Set-Content` 或管道的默认编码。
+3. 临时正文文件使用唯一的系统临时路径，只包含本次待发送文本；写入完成后传递文件路径，命令读取完成后立即删除。远端逐字比较使用内存中的最终正文，不依赖临时文件继续存在。
+
+Windows PowerShell 5.1 安全范式：
+
+```powershell
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+$bodyPath = Join-Path ([IO.Path]::GetTempPath()) ("gitcode-body-{0}.md" -f [guid]::NewGuid())
+[IO.File]::WriteAllText($bodyPath, $body, $utf8NoBom)
+try {
+    & "<gitcode-command>" issue comment <issue> -R <canonical> --body-file $bodyPath --json
+} finally {
+    Remove-Item -LiteralPath $bodyPath -Force -ErrorAction SilentlyContinue
+}
+```
+
+禁止在 Windows PowerShell 5.1 中对含中文或其他非 ASCII 字符的正文使用以下形式：
+
+```powershell
+$body | <gitcode-command> ... --body-file -
+```
+
+`$OutputEncoding` 在 Windows PowerShell 5.1 中默认不保证 UTF-8，上述裸管道会把中文替换为 `?`。若命令仅接受 stdin，必须先显式设置无 BOM UTF-8：
+
+```powershell
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+$OutputEncoding = $utf8NoBom
+[Console]::OutputEncoding = $utf8NoBom
+$body | & "<gitcode-command>" ... --body-file -
+```
+
+若 typed command 只接受 `--body`/`--comment`/`--title` 等字符串参数且当前入口是 Windows `.cmd` wrapper，不把非 ASCII 文本作为命令行参数传递。优先使用同一 CLI 的 `api --input <utf8-json-file>`，或切换到已验证的 UTF-8 文件/stdin 能力；没有安全通道时进入 `blocked`，不得冒险写入。
+
+### 写后校验与修复
+
+每次人类可读写入后，必须先通过权威 JSON 接口回读，再进行后续状态变更：
+
+1. 标题等单行字段逐字比较；正文类文本将本地预期值和远端值统一换行为 `\n` 后逐字比较完整内容，并验证末尾恰好存在一次 `——msdevflow`。
+2. 不以 CLI 写命令返回成功代替正文校验；`?`、乱码、截断、缺失尾签、重复尾签或正文不一致都视为写入未完成。
+3. 写入未完成时，立即阻断关闭 Issue、resolve discussion、CI 触发和 merge。
+4. 目标可编辑时，使用 UTF-8 文件安全通道原地修复同一 PR/评论/回复，再回读；禁止直接重复发布造成双评论。
+5. 目标不可编辑时停止并报告 comment/discussion ID 和损坏范围，等待用户决定删除、人工修改或发布更正；不得把损坏文本当作有效证据继续推进。
+
+严格 ASCII 机器协议 payload（如裸 `compile`、`/lgtm`、`/merge`）无需改写，但其独立人类可读说明评论仍必须遵循本节。
+
+## GitCode 远端文本尾签
+
+Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普通评论、discussion 回复、CI 修复说明和合入协议说明，正文末尾必须与主体间隔一个空行并恰好附加一次：
+
+```markdown
+——msdevflow
+```
+
+规则：
+
+- 用户提供核心内容也不免除尾签：只要由 Agent 执行 GitCode 正文写入，就附加尾签；不追溯修改既有人工文本，只约束本次新建或本次明确编辑的内容。
+- 同一正文只保留一个尾签。重试或更新前先比较去除唯一尾签后的正文语义，禁止重复追加；回读时按“写后校验与修复”逐字验证完整正文和尾签。
+- PR 标题、Issue 标题、commit message、分支名、标签、assignee、resolve 状态等非正文元数据不追加尾签。
+- 对必须精确匹配的机器人命令或机器协议 payload（如裸 `compile`、`/lgtm`、`/merge`），不得修改、包裹或同行追加尾签。先按幂等规则发布一条带尾签的独立人类可读说明评论，再单独发送原始 payload；两次写操作都要回读。若仓库禁止额外评论，则保持机器 payload 原样，并把该动作标记为 `signature-blocked-by-protocol`，向用户披露，不能谎称已添加尾签。
+- `code-review` 的 `/lgtm` 前置说明必须是绑定当前 `review_head_sha` 的检视摘要，包含覆盖范围和未发现需要作者修改的问题；摘要逐字回读且 head 仍稳定后才能发送正文恰好为 `/lgtm` 的独立评论。
+- 尾签只标识文本由 msdevflow 发布，不代表 reviewer/approver 身份，也不替代独立审批或仓库门禁。
+
+## 授权范围
+
+`autonomous` 授权至少包含 canonical、Issue、source、branch 和目标。授权只适用于该运行，不能扩展到其他 Issue、PR 或仓库。
+
+`autonomous-ci` 只授权在同一 PR 的 CI 修复循环中：修改与根因直接相关的代码、运行门禁、创建新 commit、push 同一 source branch、重触发 CI。它不授权扩大需求、force push、降低测试、处理 feedback、review、approve 或 merge。
+
+显式 `openlibing-auth`、显式 `ci` 和完整 E2E 均授权在需要 openLiBing OAuth 时自动安装配套 Python Playwright 依赖并打开可见浏览器，但不授权下载 Playwright Chromium。优先使用系统 Chrome/Edge，其次使用已存在的 Playwright Chromium；均不可用或 Playwright 无法启动时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。该链接只供人工浏览器访问，不能证明当前进程已认证或固定 run 已验证。该授权不允许 Agent 代替用户填写 GitCode 凭证、点击授权同意、读取浏览器 Cookie 值或导出任何 Token。
+
+## Guided 检查点
+
+开始以下动作前确认：
+
+- 创建 Issue 的最终目标、模板、标题、正文和元数据预览；
+- 自领/修改 Issue assignee 或发布接取评论；
+- 需求分析和方案选择；
+- 修改范围发生变化；
+- 首次 push；
+- 创建 PR；
+- 每个非预先授权的 CI 修复方案；
+- 发布 discussion 回复或其他人类可读远端评论；
+- 发布 `code-review` finding；
+- 发送可能触发 CI 或 merge 的机器人命令；
+- merge。
+
+`code-review` 完整检视未发现问题时，无论 guided 或 autonomous，都必须展示当前 PR、`review_head_sha`、带尾签摘要和精确 `/lgtm`，并取得一次明确确认；普通的 `action=code-review` 调用不构成该确认。
+
+本地只读探查、读取远端公开事实、运行测试和可逆代码编辑无需逐动作确认，但编辑前应已有用户确认的方案。
+
+## 永久硬停止点
+
+- 要求读取、输出、转存或持久化 GitCode Token、openLiBing Token、密码、私钥、个人数据或未公开漏洞；openLiBing OAuth Token 仅在当前认证进程内短暂使用不属于违规持久化；
+- 绕过 hooks、测试、CI、review 或 approval；
+- force push、重写共享历史、关闭 Issue、删除分支；
+- 作者自批、自造 LGTM/approved label；独立 `code-review` 必须先证明当前账号不是 PR author，且不得发送 `/approve`；
+- 公共行为、兼容性、数据格式或任务范围发生未授权变化；
+- 写操作返回不确定且无法查询远端结果；
+- merge 前状态变化或缺少当前 PR 的用户确认。
+
+## 写操作幂等规则
+
+- `create-issue` 不执行产品查重；创建结果不确定时只按目标仓库、当前账号、action 启动时间之后、标题和完整正文逐字一致做有界恢复，找到多个或不能证明唯一时停止；
+- 修改 assignee 后回读 Issue；
+- 创建 PR 前后按 canonical + source + head + base 查询；
+- 评论前按目标 discussion、正文语义和唯一尾签检查是否已有等价回复；
+- `code-review` finding 按 canonical + PR + `review_head_sha` + reviewer + path/position + 完整正文检查；检视通过按 canonical + PR + `review_head_sha` + reviewer + 带尾签摘要 + 精确 `/lgtm` 检查，旧 head 证据不得复用；
+- 严格机器协议命令前检查同一目标和协议动作的带尾签独立说明评论与命令是否已分别存在；
+- CI 使用 PR + head SHA 作为运行键；
+- resolve 前检查 `resolved`；
+- merge 前后回读 PR。
+
+写操作超时或连接中断时，先查询事实，禁止直接重试。
+
+## 恢复记录
+
+action/阶段摘要至少包括：
+
+```markdown
+- run/action/state/mode/head：
+- 输入事实：
+- canonical/source/operation target：
+- 执行动作：
+- 验证证据：
+- 用户决策：
+- 产物：
+- 阻塞或下一步：
+```
+
+默认保留在会话任务状态；只有仓库规范要求或用户授权时才写入 Issue/PR 评论。