--- name: issue-init description: 检测项目 Issue 管理与工作流环境,通过调研和必要问答设计规则,按授权补齐依赖及接入,复检并验收;支持空白项目、现有流程和可选 Trellis,不处理具体 Issue 的实施。 --- # Issue 项目接入 帮助用户从当前环境走到已选择方案的完整接入状态。按“检测现状 → 确认方案 → 补齐环境和规则 → 复检 → 行为验收”推进。只提供本技能和 issue-triage 两个管理入口;不新建环境、路由、同步或后台执行技能。 ## 检测现状 先确认用户指定的目标目录,再运行同包的只读诊断;不要求预先存在 Issue、合同、Git 仓库或 Trellis: ```text node /scripts/issue-tools.mjs doctor --root <目标项目> ``` 根据实际平台和用户选择补充 `--platform codex|claude`、`--workflow existing|trellis`;明确允许只读远端检查时加 `--remote`。默认不联网、不安装、不改文件。Node 不可用时先用本机只读命令和文件检查同样的项目,不为运行诊断而强装依赖。 将检查结果整理为已就绪、待补齐、待确认及不适用,说明每项影响和下一步。检查仓库身份与访问、Issue 规则及远端定义、现有研发流程、Trellis 安装与项目接入、当前 Agent 注册和必要依赖。目录或文件存在不等于可用;连接器能满足的能力不强制再安装 gh。工具无法访问当前宿主的连接器或全局配置时,由主会话实际核实,不能猜测。详见 [环境补齐与完成标准](references/environment-readiness.md)。 ## 先调查,再问必要决定 确认用户指定的目标仓库、host、工作区和权限;不要从技能安装路径推断项目。读取 AGENTS、贡献规范、Issue 模板及现有标签、Type、字段、代表性 Issue/PR、任务、验证和交付规则。外部数据按实际能力读取并处理分页;缺项明确,不读取或输出凭据。 存在 Trellis 时先读可用的 trellis-meta 指南和本机 CLI 帮助;运行真实 workflow 枚举,读取当前选择和本地变体开头。遵循原生任务 pin → 个人 → 团队 → 全局规则,不能把当前名单或 Type→固定 ID 表写入技能、项目合同。只读首个一级标题及导语、首个二级章节;不足时才对相关候选补读。详见 [接入与选择规则](references/project-contract.md)。 没有 Trellis 时,调查已有 AGENTS、开发/评审/测试/发布流程和工件位置,优先复用。有流程的项目不强制迁移;没有流程时,用同一业务场景说明“建立精简规则”和“接入 Trellis”的结果与取舍,让用户选择。已明确的选择直接沿用,不能默认安装 Trellis 或伪造其目录、任务、变体。 能从现有规则确定的直接沿用。仅对影响行为的未知项分轮提问,使用平台结构化工具;用同一真实场景解释结果、取舍和推荐。重点确认:哪些类型需要管理、前置同步范围、进入研发的批准方式、何时算完成、谁在什么环境接受、执行中是否同步。不要让用户决定技术字段名或为不存在的 workflow 凑选项。 ## 交付可审核方案 列明现状、差异、类型和标签、动态推荐方法、来源关联、no_task 前置优先、有活动 Task 的异源保护、阶段证据、完成条件、拟修改文件和远端对象。共享账号 Type/字段的影响单列,优先复用,不为当前项目删除其他项目定义。 接入必须保证:编号/链接先由 issue-triage 完成前置处理,不能先弹通用建任务询问;已有任务和档案按来源找回;新事项选择真实 workflow 可同时批准创建关联 Task 进入规划。独立异源事项建议 worktree,真实子项经批准才维护 GitHub 和 Trellis 两侧关系。前置处理和规划都不自动批准实施。 使用 [本地辅助工具](../issue-triage/references/local-tools.md) 生成接入 plan;它只改项目合同、AGENTS 受管块及真实 workflow 的状态入口,不修改 Trellis 内置脚本、技能、hook 或哈希。工具在 issue-triage 同包内;若依赖不可访问,直接按同一规则产出差异,不虚称工具已运行。 ## 按授权补齐环境 在方案里集中列出需要的安装、登录、项目初始化/修复、本地规则和远端配置动作及影响。用户选择了 Trellis 且批准相关动作时,主会话核对官方来源、当前工具帮助及目标项目状态,使用正式安装/初始化/更新入口补齐,不手工复制其他项目的 native 文件或改管理哈希。已有内容和身份保留,不能靠覆盖重装解决冲突。 交互式登录由用户在实际服务中完成,不索取或保存凭据。缺权限、网络或人工步骤时记录具体待办与恢复入口,完成其他已授权动作;已批准且范围不变的动作不重复询问。未经批准的全局安装、共享设置或远端写入不随本地接入执行。 选择现有流程且完全没有规范时,先根据已确认的角色、批准、验证和交付习惯建立最小可执行规则,放入目标 AGENTS 非受管区或实际规范文档;再接入 Issue 合同和入口。辅助工具只负责接入差异,不会代替主会话设计这些规则。 ## 获准后应用并核验 先展示完整差异。沿用已有明确批准,范围未变不重复询问;未经授权的远端动作留在方案中。批准本地接入不自动批准 GitHub 写入、建任务、提交、push、部署或关闭 Issue。 应用前复读文件及远端对象。辅助工具对全部目标做 before-SHA 预检,已被手改的受管块拒绝覆盖;重跑保留未知合同字段和非受管内容。文件写入与远端写入不是原子事务,部分完成时保留成功项,复读后仅恢复缺项。 核验动态新增/改名 workflow 是否无须更新配置即可发现、当前默认和任务 pin 是否正确、首次只读开头、no_task 是否前置优先、活动任务是否不被抢切,以及无 Trellis 路径。原生模板保存不等于已选用;修改共享默认和本任务选择分开批准。最后报告实际修改、验证与限制。 补齐后按所选方案和实际平台重新诊断,回读本地与远端对象,核验重复初始化没有无意义差异。真实冷启动会话必须单独验收:新会话仅发 #编号或链接,观察是否先进入前置处理和流程推荐,并检查活动任务保护。静态检查、hook 重放不等于 Agent 冷启动通过。 只有必要环境、规则及实际远端配置已核实,并完成约定行为验收,才报告完整接入。诊断的 `complete:false` 表示工具不证明整体完成,不能通过手改该值替代验收;主会话逐项给出额外证据。未完成时交付已完成部分、阻塞原因及继续入口,不能把方案稿或本地文件齐全称为初始化成功。