@godv61/dsh-task-engine 0.30.0 → 0.30.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/manual.html CHANGED
@@ -1,178 +1,175 @@
1
- <!doctype html>
2
- <html lang="zh-CN">
3
- <head>
4
- <meta charset="utf-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1">
6
- <title>DSH Task Engine · 使用手册</title>
7
- <style>
8
- :root{--ink:#172535;--muted:#526477;--line:#d8e1eb;--blue:#2155b4;--pale:#edf4ff;--paper:#f5f7fa;--white:#fff;--warn:#fff2dc}
9
- *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.75 "Microsoft YaHei","PingFang SC",system-ui,sans-serif}
10
- a{color:var(--blue)}code,pre{font-family:Consolas,"Cascadia Code",monospace}code{background:#eef2f6;padding:.1em .35em;border-radius:.25em}pre{overflow:auto;padding:1rem;background:#14243c;color:#fff;border-radius:.6rem}pre code{padding:0;background:none;color:inherit}
11
- header{padding:2.5rem max(1rem,calc((100vw - 1120px)/2));background:linear-gradient(120deg,#143775,#2760bc);color:#fff}header h1{margin:.1rem 0;font-size:2.3rem}header p{max-width:850px;margin:.4rem 0}
12
- .layout{width:min(1120px,calc(100% - 2rem));margin:2rem auto;display:grid;grid-template-columns:235px minmax(0,1fr);gap:1.5rem}nav{position:sticky;top:1rem;align-self:start;background:var(--white);border:1px solid var(--line);border-radius:.7rem;padding:1rem}nav a{display:block;padding:.24rem 0}
13
- main{min-width:0}section{background:var(--white);border:1px solid var(--line);border-radius:.8rem;padding:1.4rem;margin-bottom:1rem}h2{margin:0 0 .8rem}h3{margin:1.35rem 0 .35rem}p{margin:.5rem 0 1rem}.note{background:var(--pale);border-left:4px solid var(--blue);padding:.75rem 1rem;border-radius:.3rem}.warn{background:var(--warn);border-left-color:#bc7821}
14
- table{border-collapse:collapse;width:100%;font-size:.94rem}th,td{border:1px solid var(--line);padding:.55rem;text-align:left;vertical-align:top}th{background:#edf4ff}ul,ol{padding-left:1.45rem}li+li{margin-top:.3rem}.scroll{overflow-x:auto}
15
- @media(max-width:760px){.layout{display:block}nav{position:static;margin-bottom:1rem}nav a{display:inline-block;margin-right:.8rem}header{padding:1.5rem 1rem}}@media print{nav{display:none}.layout{display:block;width:100%}section{break-inside:avoid}}
16
- </style>
17
- </head>
18
- <body>
19
- <header>
20
- <p>DeepSeek Harness · 当前使用手册</p>
21
- <h1>DSH Task Engine</h1>
22
- <p>按每次需求选择流程,使用项目 Skill 与 Rule 复用团队规范;需要时再启用 SonarQube 审核。</p>
23
- </header>
24
- <div class="layout">
25
- <nav aria-label="目录">
26
- <strong>目录</strong>
27
- <a href="#overview">先理解工作方式</a>
28
- <a href="#install">安装与检查</a>
29
- <a href="#first-project">首次初始化项目</a>
30
- <a href="#skills">Skill 与 Rule</a>
31
- <a href="#flows">四档流程与交接</a>
32
- <a href="#task">执行一个任务</a>
33
- <a href="#tests">测试和证据</a>
34
- <a href="#sonar">配置 SonarQube</a>
35
- <a href="#findings">审核结果与误报</a>
36
- <a href="#ledger">任务台账与文件</a>
37
- <a href="#help">常见问题</a>
38
- </nav>
39
- <main>
40
- <section id="overview">
41
- <h2>先理解工作方式</h2>
42
- <p>一个项目可以有很多会话和任务。项目配置保存团队通用的 Skill、Rule 与可选 SonarQube 连接;每个<strong>新任务</strong>由模型根据需求复杂度选择一条流程,创建时冻结阶段顺序。项目配置不会把普通会话或该项目的所有任务强制放进同一流程。</p>
43
- <p>元技能负责本阶段要做什么、交给下一阶段什么;项目 Skill 说明如何在该项目做;Rule 给出具体约束。任务台账保存实施项、验证回执与审核记录。模型可以执行工作,但阶段和质量门禁由 <code>dev_task</code> 检查。</p>
44
- <div class="note">首次使用的最短路径:安装并重启 → 在工作台选择项目 → 初始化项目 Skill/Rule → 进入“工程化开发引擎”会话描述需求 → 查看任务台账。</div>
45
- </section>
46
-
47
- <section id="install">
48
- <h2>安装与检查</h2>
49
- <p>插件必须安装到你实际启动的 DSH Web profile。以下以 <code>web</code> 为例:</p>
50
- <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
51
- <p>如果通过 DSH 源码运行,在 DSH 根目录可使用:</p>
52
- <pre><code>pnpm dsh plugin --profile web add @godv61/dsh-task-engine
53
- pnpm dsh web --no-open</code></pre>
54
- <ol>
55
- <li>关闭已有的 DSH Web 进程,再用相同 profile 启动,避免旧进程继续加载旧包。</li>
56
- <li>侧边栏找到<strong>工程任务</strong>;新建会话能选<strong>工程化开发引擎</strong>。</li>
57
- <li>在工作台顶部选择项目工作区。项目路径应是代码库根目录;先确认当前 Git 分支。</li>
58
- </ol>
59
- <p>只在某个目录执行 <code>npm install</code> 不会把插件挂进 DSH profile。没有入口时先核对安装和启动的 profile,再查看 Web 启动日志。</p>
60
- </section>
61
-
62
- <section id="first-project">
63
- <h2>首次初始化项目</h2>
64
- <p>打开“工程任务 → 项目初始化”,在“项目 Skill / Rule 初始化”复制请求,把它发送到以该项目为工作区的“工程化开发引擎”会话。页面提供入口;实际扫描和写入由会话中的 <code>dev_task init_project</code> 完成。</p>
65
- <div class="scroll"><table><thead><tr><th>阶段</th><th>会发生什么</th><th>你要检查什么</th></tr></thead><tbody>
66
- <tr><td><code>inspect</code></td><td>只读扫描目录、构建清单与可证明的版本。</td><td>是否看到了主要后端、前端、脚本模块。</td></tr>
67
- <tr><td><code>propose</code></td><td>预览拟生成的 Skill、Rule、挂载关系与项目地图覆盖检查。</td><td>技术栈是否来自实际清单;项目地图是否总结整个仓库,而非当前需求。</td></tr>
68
- <tr><td><code>apply</code></td><td>按同一提案哈希写入项目文件;已有同名文件不会被静默覆盖。</td><td>查看生成的内容与绑定,再决定哪些文件提交给团队。</td></tr>
69
- </tbody></table></div>
70
- <p>常见产物是 <code>.dsh/skills/&lt;项目名&gt;-project-map/SKILL.md</code>、技术栈和后端/前端开发 Skill,以及 <code>.dsh/rules/</code> 下的项目规则。项目地图写模块职责、依赖、通用入口与版本证据;某个需求的页面、接口和验收条件放进任务产物。工作台同页的 <code>AGENTS.md</code> 生成功能是另一项操作。</p>
71
- <p>团队共享时,审阅后将 <code>.dsh/skills/</code>、<code>.dsh/rules/</code>、<code>.dsh/meta.json</code> 纳入 Git。Token 和本地审核报告不应随代码提交。</p>
72
- </section>
73
-
74
- <section id="skills">
75
- <h2>Skill 与 Rule 如何生效</h2>
76
- <p>内置核心 Skill 对应需求分析、架构设计、任务编排、代码开发、测试和代码审核。你可以给这些元技能挂载项目 Skill,并在 Skill 的 <code>profile.json</code> 配置 Rule。项目 Skill 可来自 <code>.dsh/skills/</code>,工作台也能发现 <code>.agents/skills/</code> 中的 Codex 项目技能;用户级资源可跨项目复用。</p>
77
- <p><strong>同名 Skill 的优先级:</strong>项目级优先于用户级,用户级优先于插件内置。项目同名版本使用自己的 Rule 列表,不把低优先级版本的 Rule 自动混进来。Rule 挂在 Skill 下,不是给某个阶段随意叠加;同一个 Skill 被不同元技能使用时遵守同一组 Rule。</p>
78
- <p>项目挂载保存在 <code>.dsh/meta.json</code>;工作台“自适应流程”可完成配置。编辑正文后,下一次加载读取最新文件,但已创建任务仍按创建时的阶段图和资源引用运行。删除正在引用的 Skill/Rule 会阻止流转。</p>
79
- <p>初始化生成的 Rule 应有明确触发条件、适用边界和正确示例。Sonar 审核失败后,只有<strong>真实、已修复、可复用</strong>的案例才适合用 <code>learn_rule propose → apply</code> 写入项目 Rule;误报不应被教给下一次开发。</p>
80
- </section>
81
-
82
- <section id="flows">
83
- <h2>四档流程与阶段交接</h2>
84
- <div class="scroll"><table><thead><tr><th>复杂度</th><th>典型范围</th><th>阶段顺序</th></tr></thead><tbody>
85
- <tr><td>低</td><td>边界明确的局部修改</td><td>代码开发 → 测试 → 代码审核 → 完成</td></tr>
86
- <tr><td>中</td><td>常规功能或缺陷修复</td><td>需求分析 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
87
- <tr><td>高</td><td>跨模块且存在实现先后依赖</td><td>需求分析 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
88
- <tr><td>超高</td><td>完整新模块或大范围重构</td><td>需求分析 → 架构设计 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
89
- </tbody></table></div>
90
- <p>需求分析交付目标、范围、非目标和可验证的验收条件;架构设计交付边界、影响与取舍;任务编排交付按实现先后排列的实施项 ID、依赖和交接产物;代码开发交付变更文件及逐项规格/质量审查;测试交付真实命令与覆盖说明;代码审核交付结论及可选 Sonar 报告。<strong>实施项是推进顺序,不是给团队成员派活。</strong>风险等级与复杂度独立判断。</p>
91
- </section>
92
-
93
- <section id="task">
94
- <h2>执行一个任务</h2>
95
- <ol>
96
- <li>新会话使用“工程化开发引擎”预设并描述需求。先调用 <code>dev_task status</code> 查当前工作区和分支是否已有任务;新需求用 <code>assess</code> 预览复杂度和技能,再用 <code>create</code> 创建任务。</li>
97
- <li>每阶段读取 <code>status</code> 给出的当前 Skill、Rule、必填产物和阻塞原因;用 <code>record</code> 填写当前阶段允许的字段。阶段流转使用 <code>advance</code>,不能手改任务 JSON 跳门禁。</li>
98
- <li>高、超高任务在任务计划中逐行列稳定实施项 ID,再用 <code>items</code> 登记。缺少计划项会被拒绝。<code>items</code> 默认按 ID 合并:只补 I5 不会删掉已有 I1–I4。明确要重排或删除未开始项目时才传 <code>items_mode=replace</code> 和完整目标列表;已完成或有审查记录的项仍受保护。</li>
99
- <li>实现每项时记录 <code>dispatch</code>、<code>review_item</code>;开发者可在当前会话直接实施,不要求分派给别人。变更文件登记在任务 <code>files</code> 范围内。修改代码后旧测试和审核回执会失效。</li>
100
- <li>测试阶段调用 <code>verify</code> 执行真实命令;代码审核阶段运行 <code>sonar_check</code>(若启用 Sonar),处理问题后记录 <code>review</code>。通过门禁后按 <code>status.commit</code> 的提示提交并完成任务。</li>
101
- </ol>
102
- <h3>给会话的第一条需求示例</h3>
103
- <pre><code>请在当前项目实现“设备授权范围”需求。先读取现有项目 Skill/Rule,
104
- 评估这次需求的复杂度,说明验收条件。需要任务编排时按实现先后列
105
- 实施项和依赖;开发、真实测试、代码审核都按任务台账推进。
106
- 只在当前分支工作,不要推送。</code></pre>
107
- <p>会话应先展示复杂度依据和任务状态。若发现已有任务,先核对任务 ID 与分支,避免把这条需求写进其他任务。你可以随时在“任务台账”查看它记录的实施项和下一门禁。</p>
108
- <p>一个任务只负责其记录的分支、文件范围和流程。多会话并行时应给不同任务使用独立分支或工作区,避免另一任务的未提交代码混进本次审核。</p>
109
- </section>
110
-
111
- <section id="tests">
112
- <h2>测试和证据</h2>
113
- <p><code>dev_task verify</code> 保存命令、退出码、标准输出、标准错误和文件范围指纹。退出码 0 只是必要条件;对于 Maven <code>test</code>、<code>verify</code>、<code>package</code> 或 <code>install</code> 命令,输出还必须显示 Surefire/Failsafe 至少运行一个测试。输出显示 0 个或没有测试摘要时,任务验证不通过。请使用能输出测试摘要的命令,并核对实际测试报告;不要用只编译、跳过测试的命令冒充功能验证。</p>
114
- <p>构建、单元测试、接口、数据库、页面和消息验证覆盖不同风险。缺测试账号或独立数据库时,应在交接中写清未覆盖场景,不能把编译或静态检查当成业务验收。真实命令在 DSH 会话沙箱中执行;权限被拒绝时按宿主审批提示处理,不要反复换命令绕过。</p>
115
- </section>
116
-
117
- <section id="sonar">
118
- <h2>按项目配置 SonarQube</h2>
119
- <p><strong>不需要 Sonar:</strong>保持“自适应流程”中的 Sonar 开关关闭;不必填写地址、Key 或 Token。代码审核元技能和项目 Rule 仍会运行。</p>
120
- <p><strong>需要 Sonar:</strong>先在工作台顶部选对项目,再开启 Sonar,填写服务地址、项目 Key、分析对象与扫描来源。项目 Key 在 Sonar 项目设置中查;Token 在 Sonar 个人安全设置生成,并需具备所选方式需要的分析或读取权限。Token 在同页单独保存到本机 DSH 凭据存储,按项目工作区隔离,只显示“已配置”,不会写入 <code>.dsh/meta.json</code> 或审核报告。换项目应分别配置。环境变量名可作为后备设置。</p>
121
- <div class="scroll"><table><thead><tr><th>页面字段</th><th>怎样填写</th></tr></thead><tbody>
122
- <tr><td>服务地址</td><td>填 SonarQube 根地址,例如 <code>https://sonar.example.com</code>,不带项目页面路径。</td></tr>
123
- <tr><td>项目 Key</td><td>填当前代码库在 SonarQube 中的项目标识;每个项目可不同。</td></tr>
124
- <tr><td>扫描来源</td><td>提交前检查选 <code>ide-local</code>;已有 CI 分析选 <code>ci</code>;本机上传选 <code>local</code>。</td></tr>
125
- <tr><td>分析对象</td><td>分支或合并请求,与实际扫描目标一致。本地规则审核使用分支模式。</td></tr>
126
- <tr><td>参考分支、审核路径</td><td>本地规则审核填写新代码基线和项目实际扫描的相对目录;不必把其他项目的配置复制过来。</td></tr>
127
- <tr><td>Token</td><td>当前项目单独保存;保存后只显示是否已配置,不会回显原值。</td></tr>
128
- </tbody></table></div>
129
- <div class="scroll"><table><thead><tr><th>扫描来源</th><th>何时适用</th><th>提交/推送</th><th>结果边界</th></tr></thead><tbody>
130
- <tr><td><code>ide-local</code> 本地规则审核</td><td>希望在提交前检查未提交的新代码;本机有 SonarLint 后台组件。</td><td>无需提交、无需推送。</td><td>同步项目 Quality Profile 中可本地执行的规则;不产生服务端 CE task,也不等同完整服务端 Quality Gate。</td></tr>
131
- <tr><td><code>ci</code> CI 结果</td><td>已有 CI 扫描,能取得该次分析的 CE task ID。</td><td>按 CI 触发条件提交并推送。</td><td>读取本次服务端分析的新代码问题及 Quality Gate 条件。</td></tr>
132
- <tr><td><code>local</code> 上传式本机扫描</td><td>本机能运行扫描器,SonarQube 支持保存任务分支分析。</td><td>先提交;不要求推送。</td><td>扫描上传到 Sonar 服务端,Community Build 的分支扫描会被预先拒绝。</td></tr>
133
- </tbody></table></div>
134
- <h3>本地规则审核的额外设置</h3>
135
- <p>选择 Git 参考分支或提交作为“新代码”基线;<code>include_paths</code> 填项目实际扫描的目录,例如仅后端 Maven 模块。代码审核会先用 Git 差异核对这些目录中的变更是否全部登记到任务 <code>files</code>;漏登时直接报出文件名并要求补齐,避免“只扫一部分却显示全部覆盖”。项目范围之外的前端或 SQL 不能被误称为已通过本次后端审核。</p>
136
- <p>DSH 服务进程需配置 <code>DSH_SONARLINT_JAVA</code>、<code>DSH_SONARLINT_LIB</code>、<code>DSH_SONARLINT_PLUGINS</code>,分别指向 Java、SonarLint 后台 JAR 目录和分析器 JAR;Windows 多个插件路径用分号分隔。JS/TS/Vue/CSS 分析还需要 Node.js。若项目为某种语言启用了规则而本地无法分析,报告列“未覆盖”并阻断。部分服务端规则本身无法在本地执行;需要完全相同的服务端结论时使用 CI 扫描。</p>
137
- <div class="note warn">Sonar 配置是每项目独立的;启用规则不保证规则本身适用于所有代码。碰到疑似自定义规则误报,应核对语义和证据,不应为了让计数归零而破坏业务实现。</div>
138
- </section>
139
-
140
- <section id="findings">
141
- <h2>查看问题、处理误报与沉淀规则</h2>
142
- <p>测试通过后,在“代码审核”阶段运行 <code>dev_task sonar_check</code>。任务台账可展开最近一次审核,查看来源、原始结果、问题规则、严重程度、文件位置、人工复核状态与未解决数量。每次扫描在项目 <code>.dsh/reviews/&lt;任务 ID&gt;/</code> 生成一份 Markdown 报告;项目可将该报告目录加入 <code>.gitignore</code>。结构化结果保存在 <code>.dsh/task-&lt;任务 ID&gt;.json</code>。</p>
143
- <p>真实问题:修复代码,重新验证并复扫。<strong>仅本地规则审核的误报:</strong>使用 <code>dev_task sonar_disposition</code> 指定当前报告中的 <code>issue_key</code>,说明具体误报原因并提供证据;DSH 请求人工逐条批准。批准记录写回本次任务与报告,原始规则结果仍显示原来的 <code>ERROR</code>,任务门禁另显示复核后的未解决数量。未批准、证据不足、代码变化或重新扫描后都不能沿用该处置。CI 和上传式扫描的服务端 Quality Gate 不能通过该操作绕过,应在 SonarQube 中按组织流程处理。</p>
144
- <p>你可以直接对会话说:“请打开任务台账中这条 Sonar 告警,核对代码语义并给出理由和源码证据。确认是误报后发起逐项人工复核;未经我批准不要放行,也不要修改代码来藏掉告警。”审批请求会列出规则、文件、问题编号、理由和证据。多条告警需要分别审查;一条被批准不会自动豁免同规则的其他位置。</p>
145
- <p>真实且具有通用性的修复案例,可以先用 <code>learn_rule phase=propose</code> 预览项目 Rule,再用 <code>phase=apply</code> 挂到对应开发 Skill;会影响之后创建的任务。已确认误报不列为学习候选,不自动转成团队规范。发现服务器自定义规则本身过宽时,应把例子反馈给规则维护者修正其实现或适用范围。</p>
146
- </section>
147
-
148
- <section id="ledger">
149
- <h2>任务台账与项目文件</h2>
150
- <p>“待开始”表示实施项还没执行;“实施中”表示已记录开始;“待审查”表示缺逐项规格或质量审查;“代码审核”是整个任务的后续阶段。它们是不同层级的状态,不代表已经把任务分派给团队成员。任务台账会显示当前阶段、实施项、验证回执、审核结果和可选 Sonar 明细。</p>
151
- <div class="scroll"><table><thead><tr><th>位置</th><th>用途</th><th>团队共享建议</th></tr></thead><tbody>
152
- <tr><td><code>.dsh/meta.json</code></td><td>项目元技能挂载与可选 Sonar 非秘密配置。</td><td>审阅后提交。</td></tr>
153
- <tr><td><code>.dsh/skills/</code>、<code>.dsh/rules/</code></td><td>项目 Skill、Rule 与各 Skill 的 <code>profile.json</code>。</td><td>审阅后提交。</td></tr>
154
- <tr><td><code>.dsh/task-&lt;id&gt;.json</code></td><td>该任务的阶段、实施项、回执和审核状态。</td><td>按团队任务留痕政策决定。</td></tr>
155
- <tr><td><code>.dsh/reviews/</code></td><td>逐次 Sonar Markdown 报告及误报处置。</td><td>可忽略,保留本机;不含 Token。</td></tr>
156
- <tr><td>本机 DSH 项目凭据</td><td>Sonar Token。</td><td>不提交、不回显。</td></tr>
157
- </tbody></table></div>
158
- </section>
159
-
160
- <section id="help">
161
- <h2>常见问题</h2>
162
- <h3>装好后看不到入口?</h3>
163
- <p>检查插件是否装在正在运行的 Web profile,关闭旧 Web 进程并重启,查看启动日志。普通预设与“工程化开发引擎”预设的工具不同。</p>
164
- <h3>为什么初始化没有直接生成文件?</h3>
165
- <p>工作台提供复制请求;在项目根目录的工程化会话中执行 <code>init_project inspect → propose → apply</code>,应用前需审阅提案。</p>
166
- <h3>为什么 Maven 显示构建成功,任务仍不能前进?</h3>
167
- <p>如果验证命令是 Maven 测试目标,插件还要求输出中有至少一个实际测试。检查 Surefire 版本、是否跳过测试、JUnit 引擎和测试摘要;重新运行可见摘要的命令。</p>
168
- <h3>为什么 Sonar 报了业务上必须创建的对象?</h3>
169
- <p>自定义规则可能过宽。保留告警,核查每行对象是否必须独立;本地分析可逐条提交证据由人批准,服务端规则仍应由维护者修正。不要复用同一个实体或挪代码隐藏告警。</p>
170
- <h3>为什么审核提示补文件范围?</h3>
171
- <p>本次项目扫描范围内有 Git 新增/修改文件未登记到任务 <code>files</code>。核对提示的文件是否属于本任务;属于则补进 <code>scope</code> 并重新验证,不属于则使用独立分支或工作区隔离任务。</p>
172
- <h3>已有任务会随着项目配置改变吗?</h3>
173
- <p>不会更换创建时冻结的阶段图和资源引用;所引用 Skill/Rule 的正文下一次读取会更新。代码、范围或规则变化后,应重新检查证据、测试和审核。</p>
174
- </section>
175
- </main>
176
- </div>
177
- </body>
178
- </html>
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>DSH Task Engine · 使用手册</title>
7
+ <style>
8
+ :root{--ink:#172535;--muted:#526477;--line:#d8e1eb;--blue:#2155b4;--pale:#edf4ff;--paper:#f5f7fa;--white:#fff;--warn:#fff2dc}
9
+ *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.75 "Microsoft YaHei","PingFang SC",system-ui,sans-serif}
10
+ a{color:var(--blue)}code,pre{font-family:Consolas,"Cascadia Code",monospace}code{background:#eef2f6;padding:.1em .35em;border-radius:.25em}pre{overflow:auto;padding:1rem;background:#14243c;color:#fff;border-radius:.6rem}pre code{padding:0;background:none;color:inherit}
11
+ header{padding:2.5rem max(1rem,calc((100vw - 1120px)/2));background:linear-gradient(120deg,#143775,#2760bc);color:#fff}header h1{margin:.1rem 0;font-size:2.3rem}header p{max-width:850px;margin:.4rem 0}
12
+ .layout{width:min(1120px,calc(100% - 2rem));margin:2rem auto;display:grid;grid-template-columns:235px minmax(0,1fr);gap:1.5rem}nav{position:sticky;top:1rem;align-self:start;background:var(--white);border:1px solid var(--line);border-radius:.7rem;padding:1rem}nav a{display:block;padding:.24rem 0}
13
+ main{min-width:0}section{background:var(--white);border:1px solid var(--line);border-radius:.8rem;padding:1.4rem;margin-bottom:1rem}h2{margin:0 0 .8rem}h3{margin:1.35rem 0 .35rem}p{margin:.5rem 0 1rem}.note{background:var(--pale);border-left:4px solid var(--blue);padding:.75rem 1rem;border-radius:.3rem}.warn{background:var(--warn);border-left-color:#bc7821}
14
+ table{border-collapse:collapse;width:100%;font-size:.94rem}th,td{border:1px solid var(--line);padding:.55rem;text-align:left;vertical-align:top}th{background:#edf4ff}ul,ol{padding-left:1.45rem}li+li{margin-top:.3rem}.scroll{overflow-x:auto}
15
+ @media(max-width:760px){.layout{display:block}nav{position:static;margin-bottom:1rem}nav a{display:inline-block;margin-right:.8rem}header{padding:1.5rem 1rem}}@media print{nav{display:none}.layout{display:block;width:100%}section{break-inside:avoid}}
16
+ </style>
17
+ </head>
18
+ <body>
19
+ <header>
20
+ <p>DeepSeek Harness · 当前使用手册</p>
21
+ <h1>DSH Task Engine</h1>
22
+ <p>按每次需求选择流程,使用项目 Skill 与 Rule 复用团队规范;需要时再启用 SonarQube 审核。</p>
23
+ </header>
24
+ <div class="layout">
25
+ <nav aria-label="目录">
26
+ <strong>目录</strong>
27
+ <a href="#overview">先理解工作方式</a>
28
+ <a href="#install">安装与检查</a>
29
+ <a href="#first-project">首次初始化项目</a>
30
+ <a href="#skills">Skill 与 Rule</a>
31
+ <a href="#flows">四档流程与交接</a>
32
+ <a href="#task">执行一个任务</a>
33
+ <a href="#tests">测试和证据</a>
34
+ <a href="#sonar">配置 SonarQube</a>
35
+ <a href="#findings">审核结果与误报</a>
36
+ <a href="#ledger">任务台账与文件</a>
37
+ <a href="#help">常见问题</a>
38
+ </nav>
39
+ <main>
40
+ <section id="overview">
41
+ <h2>先理解工作方式</h2>
42
+ <p>一个项目可以有很多会话和任务。项目配置保存团队通用的 Skill、Rule 与可选 SonarQube 连接;每个<strong>新任务</strong>由模型根据需求复杂度选择一条流程,创建时冻结阶段顺序。项目配置不会把普通会话或该项目的所有任务强制放进同一流程。</p>
43
+ <p>元技能负责本阶段要做什么、交给下一阶段什么;项目 Skill 说明如何在该项目做;Rule 给出具体约束。任务台账保存实施项、验证回执与审核记录。模型可以执行工作,但阶段和质量门禁由 <code>dev_task</code> 检查。</p>
44
+ <div class="note">首次使用的最短路径:安装并重启 → 在工作台选择项目 → 初始化项目 Skill/Rule → 进入“工程化开发引擎”会话描述需求 → 查看任务台账。</div>
45
+ </section>
46
+
47
+ <section id="install">
48
+ <h2>安装与检查</h2>
49
+ <p>插件必须安装到你实际启动的 DSH Web profile。以下以 <code>web</code> 为例:</p>
50
+ <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
51
+ <p>如果通过 DSH 源码运行,在 DSH 根目录可使用:</p>
52
+ <pre><code>pnpm dsh plugin --profile web add @godv61/dsh-task-engine
53
+ pnpm dsh web --no-open</code></pre>
54
+ <ol>
55
+ <li>关闭已有的 DSH Web 进程,再用相同 profile 启动,避免旧进程继续加载旧包。</li>
56
+ <li>侧边栏找到<strong>工程任务</strong>;新建会话能选<strong>工程化开发引擎</strong>。</li>
57
+ <li>在工作台顶部选择项目工作区。项目路径应是代码库根目录;先确认当前 Git 分支。</li>
58
+ </ol>
59
+ <p>只在某个目录执行 <code>npm install</code> 不会把插件挂进 DSH profile。没有入口时先核对安装和启动的 profile,再查看 Web 启动日志。</p>
60
+ </section>
61
+
62
+ <section id="first-project">
63
+ <h2>首次初始化项目</h2>
64
+ <p>打开“工程任务 → 项目初始化”,选择项目根目录,点击<strong>扫描并生成提案</strong>。工作台读取目录、构建文件和部分代表性源码,由默认模型生成 Skill / Rule 草稿。无需复制请求到会话。逐项检查正文、简介、元技能挂载和 Rule 关联;编辑或移除建议后点击<strong>检查修改</strong>,最后点击<strong>确认写入项目</strong>。</p>
65
+ <div class="scroll"><table><thead><tr><th>阶段</th><th>会发生什么</th><th>你要检查什么</th></tr></thead><tbody>
66
+ <tr><td>扫描并生成提案</td><td>只读扫描目录、构建清单和部分源码,由默认模型生成草稿。</td><td>是否看到了主要后端、前端、脚本模块。</td></tr>
67
+ <tr><td>检查修改</td><td>预览并校验 Skill、Rule、挂载关系与项目地图覆盖。</td><td>技术栈是否来自实际清单;项目地图是否总结整个仓库,而非当前需求。</td></tr>
68
+ <tr><td>确认写入项目</td><td>按同一提案哈希写入项目文件;已有同名文件不会被静默覆盖。</td><td>查看生成的内容与绑定,再决定哪些文件提交给团队。</td></tr>
69
+ </tbody></table></div>
70
+ <p>常见产物是 <code>.dsh/skills/&lt;项目名&gt;-project-map/SKILL.md</code>、技术栈和后端/前端开发 Skill,以及 <code>.dsh/rules/</code> 下的项目规则。项目地图写模块职责、依赖、通用入口与版本证据;某个需求的页面、接口和验收条件放进任务产物。工作台同页的 <code>AGENTS.md</code> 生成功能是另一项操作。</p>
71
+ <p>团队共享时,审阅后将 <code>.dsh/skills/</code>、<code>.dsh/rules/</code>、<code>.dsh/meta.json</code> 纳入 Git。Token 和本地审核报告不应随代码提交。</p>
72
+ </section>
73
+
74
+ <section id="skills">
75
+ <h2>Skill 与 Rule 如何生效</h2>
76
+ <p>内置核心 Skill 对应需求分析、架构设计、任务编排、代码开发、测试和代码审核。你可以给这些元技能挂载项目 Skill,并在 Skill 的 <code>profile.json</code> 配置 Rule。项目 Skill 可来自 <code>.dsh/skills/</code>,工作台也能发现 <code>.agents/skills/</code> 中的 Codex 项目技能;用户级资源可跨项目复用。</p>
77
+ <p><strong>同名 Skill 的优先级:</strong>项目级优先于用户级,用户级优先于插件内置。项目同名版本使用自己的 Rule 列表,不把低优先级版本的 Rule 自动混进来。Rule 挂在 Skill 下,不是给某个阶段随意叠加;同一个 Skill 被不同元技能使用时遵守同一组 Rule。</p>
78
+ <p>项目挂载保存在 <code>.dsh/meta.json</code>;工作台“自适应流程”可完成配置。左侧选择元技能,右侧查看核心与已挂载 Skill;可以搜索要挂载的 Skill。点击 Skill 旁的“配置 Rule”会打开右侧抽屉,可按名称、来源或已选状态筛选规则。项目挂载使用页面底部的“保存自适应配置”,Rule 抽屉单独保存 Skill 的规则档案。编辑正文后,下一次加载读取最新文件,但已创建任务仍按创建时的阶段图和资源引用运行。删除正在引用的 Skill/Rule 会阻止流转。</p>
79
+ <p>初始化生成的 Rule 应有明确触发条件、适用边界和正确示例。Sonar 审核失败后,只有<strong>真实、已修复、可复用</strong>的案例才适合用 <code>learn_rule propose → apply</code> 写入项目 Rule;误报不应被教给下一次开发。</p>
80
+ </section>
81
+
82
+ <section id="flows">
83
+ <h2>四档流程与阶段交接</h2>
84
+ <div class="scroll"><table><thead><tr><th>复杂度</th><th>典型范围</th><th>阶段顺序</th></tr></thead><tbody>
85
+ <tr><td>低</td><td>边界明确的局部修改</td><td>代码开发 → 测试 → 代码审核 → 完成</td></tr>
86
+ <tr><td>中</td><td>常规功能或缺陷修复</td><td>需求分析 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
87
+ <tr><td>高</td><td>跨模块且存在实现先后依赖</td><td>需求分析 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
88
+ <tr><td>超高</td><td>完整新模块或大范围重构</td><td>需求分析 → 架构设计 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
89
+ </tbody></table></div>
90
+ <p>需求分析交付目标、范围、非目标和可验证的验收条件;架构设计交付边界、影响与取舍;任务编排交付按实现先后排列的实施项 ID、依赖和交接产物;代码开发交付变更文件及逐项规格/质量审查;测试交付真实命令与覆盖说明;代码审核交付结论及可选 Sonar 报告。<strong>实施项是推进顺序,不是给团队成员派活。</strong>风险等级与复杂度独立判断。</p>
91
+ </section>
92
+
93
+ <section id="task">
94
+ <h2>执行一个任务</h2>
95
+ <ol>
96
+ <li>新会话使用“工程化开发引擎”预设并描述需求。先调用 <code>dev_task status</code> 查当前工作区和分支是否已有任务;新需求用 <code>assess</code> 预览复杂度和技能,再用 <code>create</code> 创建任务。</li>
97
+ <li>每阶段读取 <code>status</code> 给出的当前 Skill、Rule、必填产物和阻塞原因;用 <code>record</code> 填写当前阶段允许的字段。阶段流转使用 <code>advance</code>,不能手改任务 JSON 跳门禁。</li>
98
+ <li>高、超高任务在任务计划中逐行列稳定实施项 ID,再用 <code>items</code> 登记。缺少计划项会被拒绝。<code>items</code> 默认按 ID 合并:只补 I5 不会删掉已有 I1–I4。明确要重排或删除未开始项目时才传 <code>items_mode=replace</code> 和完整目标列表;已完成或有审查记录的项仍受保护。</li>
99
+ <li>实现每项时记录 <code>dispatch</code>、<code>review_item</code>;开发者可在当前会话直接实施,不要求分派给别人。变更文件登记在任务 <code>files</code> 范围内。修改代码后旧测试和审核回执会失效。</li>
100
+ <li>测试阶段调用 <code>verify</code> 执行真实命令;代码审核阶段运行 <code>sonar_check</code>(若启用 Sonar),处理问题后记录 <code>review</code>。通过门禁后按 <code>status.commit</code> 的提示提交并完成任务。</li>
101
+ </ol>
102
+ <h3>给会话的第一条需求示例</h3>
103
+ <pre><code>请在当前项目实现“设备授权范围”需求。先读取现有项目 Skill/Rule,
104
+ 评估这次需求的复杂度,说明验收条件。需要任务编排时按实现先后列
105
+ 实施项和依赖;开发、真实测试、代码审核都按任务台账推进。
106
+ 只在当前分支工作,不要推送。</code></pre>
107
+ <p>会话应先展示复杂度依据和任务状态。若发现已有任务,先核对任务 ID 与分支,避免把这条需求写进其他任务。你可以随时在“任务台账”查看它记录的实施项和下一门禁。</p>
108
+ <p>一个任务只负责其记录的分支、文件范围和流程。多会话并行时应给不同任务使用独立分支或工作区,避免另一任务的未提交代码混进本次审核。</p>
109
+ </section>
110
+
111
+ <section id="tests">
112
+ <h2>测试和证据</h2>
113
+ <p><code>dev_task verify</code> 保存命令、退出码、标准输出、标准错误和文件范围指纹。退出码 0 只是必要条件;对于 Maven <code>test</code>、<code>verify</code>、<code>package</code> 或 <code>install</code> 命令,输出还必须显示 Surefire/Failsafe 至少运行一个测试。输出显示 0 个或没有测试摘要时,任务验证不通过。请使用能输出测试摘要的命令,并核对实际测试报告;不要用只编译、跳过测试的命令冒充功能验证。</p>
114
+ <p>构建、单元测试、接口、数据库、页面和消息验证覆盖不同风险。缺测试账号或独立数据库时,应在交接中写清未覆盖场景,不能把编译或静态检查当成业务验收。真实命令在 DSH 会话沙箱中执行;权限被拒绝时按宿主审批提示处理,不要反复换命令绕过。</p>
115
+ </section>
116
+
117
+ <section id="sonar">
118
+ <h2>按项目配置 SonarQube</h2>
119
+ <p><strong>不需要 Sonar:</strong>保持“自适应流程”中的 Sonar 开关关闭;不必填写地址、Key 或 Token。代码审核元技能和项目 Rule 仍会运行。</p>
120
+ <p><strong>需要 Sonar:</strong>先在工作台顶部选对项目,再开启 Sonar,填写服务地址和项目 Key。项目 Key 在 Sonar 项目设置中查;Token 在 Sonar 个人安全设置生成,需能读取该项目的规则。Token 在同页单独保存到本机 DSH 凭据存储,按项目工作区隔离,只显示“已配置”,不会写入 <code>.dsh/meta.json</code> 或审核报告。换项目应分别配置。</p>
121
+ <div class="scroll"><table><thead><tr><th>页面字段</th><th>怎样填写</th></tr></thead><tbody>
122
+ <tr><td>服务地址</td><td>填 SonarQube 根地址,例如 <code>https://sonar.example.com</code>,不带项目页面路径。</td></tr>
123
+ <tr><td>项目 Key</td><td>填当前代码库在 SonarQube 中的项目标识;每个项目可不同。</td></tr>
124
+ <tr><td>Git 参考版本</td><td>高级设置;默认 <code>HEAD</code>,审核尚未提交的变更。需要时可填写本机已有的分支或提交。</td></tr>
125
+ <tr><td>审核路径</td><td>高级设置;留空审核本次任务全部代码。若只需后端审核,填写项目相对目录。</td></tr>
126
+ <tr><td>Token</td><td>当前项目单独保存;保存后只显示是否已配置,不会回显原值。</td></tr>
127
+ </tbody></table></div>
128
+ <p>保存项目配置和 Token 后,管理员可点击<strong>安装或检查本地分析器</strong>。页面显示各语言生效规则数与分析器状态;检查不会审核或上传项目代码。未预先点击也可以继续开发,代码审核时会自动准备本机组件。</p>
129
+ <h3>提交前审核如何运行</h3>
130
+ <p>测试通过并进入代码审核阶段后,代码审核元技能自动调用 <code>dev_task sonar_check</code>。默认以 <code>HEAD</code> 为基线,分析任务中尚未提交的 Git 变更行;无需提交、推送或在页面手动发起。首次审核会下载并校验官方 SonarLint 后台组件,保存在运行 DSH 的用户目录 <code>~/.dsh/sonarlint-runtime/</code>;组件再从 SonarQube 同步当前项目的语言分析器和 Quality Profile 规则。首次安装要求可访问 Maven Central 和 SonarQube。通常无需安装 IDEA、Maven、SonarScanner 或单独配置 JDK;JS/TS/Vue/CSS 分析仍可能需要 Node.js。</p>
131
+ <p>首次下载约 93 MiB,慢速网络可能等待较久。若运行 DSH 的机器访问 Maven Central 需要代理,请在启动 DSH 前设置 <code>DSH_SONARLINT_PROXY=http://127.0.0.1:7897</code>(替换为实际地址),或使用 <code>HTTPS_PROXY</code>,然后重启 DSH。代理是安装组件的本机网络设置,不写入项目配置。已经手工安装后台组件时,可选用 <code>DSH_SONARLINT_JAVA</code> 和 <code>DSH_SONARLINT_LIB</code> 指向现有安装。</p>
132
+ <p>若只审后端代码,在高级设置的“审核路径”填写相对目录,例如 Maven 模块。审核前会检查这些目录的 Git 变更是否全部登记到任务 <code>files</code>;漏登会报出文件名。项目范围外的前端或 SQL 不会被称为已通过本次审核。报告列出项目生效规则数量、分析器状态和未覆盖文件;相关语言未覆盖时会阻断。</p>
133
+ <p>SonarLint 只能运行支持本地分析的服务端规则;本地通过不等于完整 SonarQube Quality Gate 通过。涉及全项目数据流、跨文件上下文或只在服务端实现的规则,仍以团队 CI 扫描为准。旧任务原有的审核设置可以继续读取,新项目页面只提供提交前审核。</p>
134
+ <div class="note warn">Sonar 配置是每项目独立的;启用规则不保证规则本身适用于所有代码。碰到疑似自定义规则误报,应核对语义和证据,不应为了让计数归零而破坏业务实现。</div>
135
+ </section>
136
+
137
+ <section id="findings">
138
+ <h2>查看问题、处理误报与沉淀规则</h2>
139
+ <p>测试通过后,代码审核元技能会自动运行 <code>dev_task sonar_check</code>。任务台账可展开最近一次审核,查看原始结果、问题规则、严重程度、文件位置、分析器状态、人工复核状态与未解决数量。每次扫描在项目 <code>.dsh/reviews/&lt;任务 ID&gt;/</code> 生成一份 Markdown 报告;项目可将该报告目录加入 <code>.gitignore</code>。结构化结果保存在 <code>.dsh/task-&lt;任务 ID&gt;.json</code>。</p>
140
+ <p>真实问题:修复代码,重新验证并复扫。疑似本地规则误报:使用 <code>dev_task sonar_disposition</code> 指定当前报告中的 <code>issue_key</code>,说明具体原因并提供证据;DSH 请求人工逐条批准。批准记录写回本次任务与报告,原始规则结果仍显示原来的 <code>ERROR</code>,任务门禁另显示复核后的未解决数量。未批准、证据不足、代码变化或重新扫描后都不能沿用该处置。服务端 Quality Gate 仍按 SonarQube 中的团队流程处理。</p>
141
+ <p>你可以直接对会话说:“请打开任务台账中这条 Sonar 告警,核对代码语义并给出理由和源码证据。确认是误报后发起逐项人工复核;未经我批准不要放行,也不要修改代码来藏掉告警。”审批请求会列出规则、文件、问题编号、理由和证据。多条告警需要分别审查;一条被批准不会自动豁免同规则的其他位置。</p>
142
+ <p>真实且具有通用性的修复案例,可以先用 <code>learn_rule phase=propose</code> 预览项目 Rule,再用 <code>phase=apply</code> 挂到对应开发 Skill;会影响之后创建的任务。已确认误报不列为学习候选,不自动转成团队规范。发现服务器自定义规则本身过宽时,应把例子反馈给规则维护者修正其实现或适用范围。</p>
143
+ </section>
144
+
145
+ <section id="ledger">
146
+ <h2>任务台账与项目文件</h2>
147
+ <p>“待开始”表示实施项还没执行;“实施中”表示已记录开始;“待审查”表示缺逐项规格或质量审查;“代码审核”是整个任务的后续阶段。它们是不同层级的状态,不代表已经把任务分派给团队成员。任务台账会显示当前阶段、实施项、验证回执、审核结果和可选 Sonar 明细。</p>
148
+ <div class="scroll"><table><thead><tr><th>位置</th><th>用途</th><th>团队共享建议</th></tr></thead><tbody>
149
+ <tr><td><code>.dsh/meta.json</code></td><td>项目元技能挂载与可选 Sonar 非秘密配置。</td><td>审阅后提交。</td></tr>
150
+ <tr><td><code>.dsh/skills/</code>、<code>.dsh/rules/</code></td><td>项目 Skill、Rule 与各 Skill 的 <code>profile.json</code>。</td><td>审阅后提交。</td></tr>
151
+ <tr><td><code>.dsh/task-&lt;id&gt;.json</code></td><td>该任务的阶段、实施项、回执和审核状态。</td><td>按团队任务留痕政策决定。</td></tr>
152
+ <tr><td><code>.dsh/reviews/</code></td><td>逐次 Sonar Markdown 报告及误报处置。</td><td>可忽略,保留本机;不含 Token。</td></tr>
153
+ <tr><td>本机 DSH 项目凭据</td><td>Sonar Token。</td><td>不提交、不回显。</td></tr>
154
+ </tbody></table></div>
155
+ </section>
156
+
157
+ <section id="help">
158
+ <h2>常见问题</h2>
159
+ <h3>装好后看不到入口?</h3>
160
+ <p>检查插件是否装在正在运行的 Web profile,关闭旧 Web 进程并重启,查看启动日志。普通预设与“工程化开发引擎”预设的工具不同。</p>
161
+ <h3>为什么初始化没有直接生成文件?</h3>
162
+ <p>工作台会先生成供审阅的草稿,不会在扫描时直接写文件。检查通过后,点击“确认写入项目”。若提示没有默认模型,先在 DSH“模型”页选择模型。工程化会话也保留 <code>init_project inspect → propose → apply</code> 的调用方式。</p>
163
+ <h3>为什么 Maven 显示构建成功,任务仍不能前进?</h3>
164
+ <p>如果验证命令是 Maven 测试目标,插件还要求输出中有至少一个实际测试。检查 Surefire 版本、是否跳过测试、JUnit 引擎和测试摘要;重新运行可见摘要的命令。</p>
165
+ <h3>为什么 Sonar 报了业务上必须创建的对象?</h3>
166
+ <p>自定义规则可能过宽。保留告警,核查每行对象是否必须独立;本地分析可逐条提交证据由人批准,服务端规则仍应由维护者修正。不要复用同一个实体或挪代码隐藏告警。</p>
167
+ <h3>为什么审核提示补文件范围?</h3>
168
+ <p>本次项目扫描范围内有 Git 新增/修改文件未登记到任务 <code>files</code>。核对提示的文件是否属于本任务;属于则补进 <code>scope</code> 并重新验证,不属于则使用独立分支或工作区隔离任务。</p>
169
+ <h3>已有任务会随着项目配置改变吗?</h3>
170
+ <p>不会更换创建时冻结的阶段图和资源引用;所引用 Skill/Rule 的正文下一次读取会更新。代码、范围或规则变化后,应重新检查证据、测试和审核。</p>
171
+ </section>
172
+ </main>
173
+ </div>
174
+ </body>
175
+ </html>