docs: add common task guidance

Author: rockyshi1993

README.md

@@ -25,6 +25,7 @@ DevCodex 不替代业务框架、GitHub CI、安全审计或人工评审。它
 - [5 分钟开始](#5-分钟开始)
 - [项目 Profile](#项目-profile)
 - [首次信任提示](#首次信任提示)
+- [常见任务怎么说](#常见任务怎么说)
 - [更新](#更新)
 - [卸载](#卸载)
 - [运行态检查](#运行态检查)
@@ -222,6 +223,78 @@ DevCodex 会按任务意图选择流程和 Skill。普通使用者不需要手
 
 `extensions.devcodex.autoAliases` 用于替换全局默认别名；省略该字段表示继续使用默认 `@rocky`，设置为空数组 `[]` 表示关闭默认自动推进别名。
 
+## 常见任务怎么说
+
+你不需要记住工作流名称、Skill 名或内部阶段。直接说明任务目标即可；为了减少来回确认，推荐把请求写成：
+
+```text
+是否自动推进 + 目标或问题 + 范围与约束 + 验证要求 + 是否提交、推送或发布
+```
+
+### 只分析，不修改
+
+```text
+分析当前项目的主要问题，按优先级给出建议。只分析，不修改文件。
+```
+
+### 整理新需求，确认后再实施
+
+```text
+分析当前项目，整理“用户登录限流”需求，列出目标、范围、用户流程、验收标准和影响，先给我确认，不要修改源码。
+```
+
+确认需求后可以继续说：
+
+```text
+确认，按刚才的需求实施，完成后运行相关测试并提交。
+```
+
+### 诊断 Bug，但暂不修复
+
+```text
+检查支付回调偶发重复入账的问题，复现并定位根因，给出影响范围和修复方案。只诊断，不修改文件。
+```
+
+### 自动修复并验证
+
+```text
+@rocky 修复当前失败的 GitHub CI，检查是否还有同类问题，运行完整验证，完成后提交。
+```
+
+### 深度审查
+
+```text
+从用户体验、架构、兼容性、测试和发布风险审查当前实现，只报告有证据的问题，不修改文件。
+```
+
+### 在新会话继续任务
+
+```text
+继续<任务名>任务
+```
+
+例如：
+
+```text
+继续用户登录限流任务
+```
+
+### 明确要求发布
+
+提交、push、tag、GitHub Release 和 npm publish 都属于独立动作。需要发布时请直接写明：
+
+```text
+@rocky 完成修复和全部验证后提交并推送 main，发布新的 patch 版本到 npm 和 GitHub Release，再用线上包重新安装验证。
+```
+
+几个实用技巧：
+
+- 只想要结论时写清楚“只分析，不修改文件”。
+- 指定项目、目录或文件范围，避免在多项目 workspace 中产生歧义。
+- 写明必须运行的测试，或要求 DevCodex 根据影响范围选择验证。
+- “完成”不自动等于 commit、push 或发布；这些动作需要在当前请求中明确写出。
+- `@rocky` 只负责在已授权范围内自动推进，不会扩大删除、越界访问或发布权限。
+
 ## 更新
 
 ```bash

changelogs/unreleased.md

@@ -4,6 +4,7 @@
 > **当前**: v1.16.1 已归档到 `changelogs/releases/v1.16.1.md`；本文件仅保留历史锚点索引与镜像供 validate 探针消费。发版后新实现再写入下方「当前未发布」。
 
 ## 当前未发布实现候选
+- **README 常见任务与 CLI 帮助防误写**：公共 README 新增可直接复制的分析、需求确认、Bug 诊断、`@rocky` 自动修复、深度审查、任务续接和发布请求教程；`devcodex help <command>` 与 `<command> --help` 现统一进入只读帮助，不再误执行 `init` 或进入子命令解析。`PublicReadmeContractV1` 和 CLI registry 负向探针防止教程或零写入语义回归。
 - **v1.16.1 已归档**：长会话提示有界化、会话治理状态隔离、项目绑定稳定性与唯一短名解析修复已进入 `changelogs/releases/v1.16.1.md`。
 - **v1.16.0 已归档**：首次初始化、项目 Profile、用户语言与 workspace runtime-state 一致性已进入 `changelogs/releases/v1.16.0.md`。
 - **v1.15.9 已归档**：SkillRoute 相同语义 rebind 现在可迁移未完成阶段前缀、重新签发新 plan cursor，并让 rebind/status/Stop 返回一致且可执行的恢复调用；语义、阶段内容或依赖漂移仍 fail closed。

scripts/lib/canonical-consumer-contracts.js

@@ -50,10 +50,15 @@ const PUBLIC_README_REQUIRED_MARKERS = Object.freeze([
   '<你的项目根目录>/.devcodex/workspace/skills/<id>/SKILL.md',
   'DevCodex 不扫描、复制、合并、覆盖或删除这些用户资产',
   '不替代业务框架、GitHub CI、安全审计或人工评审',
+  '## 常见任务怎么说',
+  '只分析，不修改文件',
+  '继续<任务名>任务',
+  'push、tag、GitHub Release 和 npm publish',
   '[AGPL-3.0](LICENSE)',
   '## 目录',
   '[为什么需要 DevCodex？](#为什么需要-devcodex)',
   '[5 分钟开始](#5-分钟开始)',
+  '[常见任务怎么说](#常见任务怎么说)',
   '[添加自己的 Skill](#添加自己的-skill)',
   '[许可证](#许可证)'
 ])

scripts/lib/cli-command-registry.js

@@ -66,16 +66,25 @@ function isVersionCommand(cmd) {
   return cmd === 'version' || cmd === '--version' || cmd === '-v'
 }
 
+function isHelpFlag(value) {
+  return value === '--help' || value === '-h'
+}
+
 function runCliCommand({ cmd, argv, registry, runMigrateLayout, process, c, console, packageVersion = null }) {
   if (isHelpCommand(cmd)) {
-    registry.cmdHelp()
+    registry.cmdHelp(cmd === 'help' && argv.length ? argv : undefined)
     return 'help'
   }
   if (isVersionCommand(cmd)) {
     console.log(packageVersion || 'unknown')
     return 'version'
   }
 
+  if (argv.some(isHelpFlag)) {
+    registry.cmdHelp([cmd, ...argv.filter(item => !isHelpFlag(item))])
+    return 'help'
+  }
+
   const selection = parseHostSelection(argv)
   if (!selection.ok) {
     console.log(c.red(`  ${selection.code}: ${selection.message}`))

scripts/lib/cli-maintenance-commands.js

@@ -1024,26 +1024,65 @@ function buildCliMaintenanceCommands(ctx) {
     }
   }
 
-  function cmdHelp() {
+  function cmdHelp(topicInput) {
+    const topicParts = Array.isArray(topicInput)
+      ? topicInput.map(item => String(item || '').trim()).filter(Boolean)
+      : (topicInput ? [String(topicInput).trim()] : [])
+    const topic = topicParts[0] || null
+    const detail = {
+      init: ['devcodex init [--profile <project>] [--dry-run]', 'Initialize the current workspace .devcodex state and Profile baseline.'],
+      update: ['devcodex update [--dry-run]', 'Refresh only the current workspace .devcodex runtime state.'],
+      status: ['devcodex status [--completion] [--json]', 'Show workspace and user-global adapter readiness.'],
+      doctor: ['devcodex doctor [--completion] [--json]', 'Diagnose adapter, native host and workflow readiness.'],
+      profile: ['devcodex profile plan|init [--tier <tier>] [--dry-run] [--force] [--prod]', 'Preview or create an advanced project Profile. Ordinary workspaces only need `devcodex init`.'],
+      runtime: ['devcodex runtime status|prune [--dry-run|--apply] [--json]', 'Inspect runtime-state usage or preview safe stale-temp cleanup.'],
+      uninstall: ['npm uninstall -g devcodex', 'Remove the published global package.'],
+      'global-adapters': ['devcodex global-adapters apply [--dry-run] [--json]', 'Advanced: refresh user-global host adapters from the current package root.'],
+      grok: ['devcodex grok [Grok CLI options]', 'Launch Grok with the user-global DevCodex kernel.'],
+      'migrate-layout': ['devcodex migrate-layout plan|apply|rollback', 'Advanced: manage centralized workspace layout migration.'],
+      probe: ['devcodex probe <id> [--json]', 'Advanced: run bounded local-only diagnostics.'],
+      trace: ['devcodex trace show|replay [options]', 'Advanced: inspect or replay LocalTaskTrace evidence.'],
+      skill: ['devcodex skill plan|resolve [options]', 'Advanced: inspect Skill resolution; ordinary users do not configure built-in Skills.'],
+      task: ['devcodex task resolve|verify|risk [options]', 'Advanced: inspect task identity, reconciliation or explicit risk decisions.']
+    }[topic]
+
+    if (topic && detail) {
+      console.log(`
+    ${c.bold(`DevCodex ${topic} help`)}
+
+    ${c.bold('Usage:')}
+      ${detail[0]}
+
+    ${detail[1]}
+
+    Run ${c.cyan('devcodex help')} for the command overview.
+    User guide: https://github.com/devcodex-labs/devcodex#readme
+  `)
+      return
+    }
+
     console.log(`
     ${c.bold('DevCodex')} — AI-powered development workflow rules for Copilot, Claude, Codex, Gemini & Grok
 
     ${c.bold('Usage:')}
       devcodex <command> [options]
       npx devcodex <command> [options]   ${c.dim('(without npm link)')}
 
-    ${c.bold('Commands:')}
+    ${c.bold('Everyday commands:')}
       ${c.cyan('init')}              Initialize workspace-owned .devcodex runtime state only
       ${c.cyan('update')}            Refresh workspace-owned .devcodex runtime state only
-      ${c.cyan('global-adapters')}   Apply user-level host adapters from package root (source-friendly)
-      ${c.cyan('grok')}              Launch Grok with the user-global DevCodex kernel
-      ${c.cyan('migrate-layout')}    Plan/apply/rollback centralized .devcodex workspace layout
+      ${c.cyan('status')}            Check workspace and host adapter readiness
+      ${c.cyan('doctor')}            Diagnose installation or workflow problems
       ${c.cyan('runtime status')}    Inspect runtime-state owners, size and last-use timestamps
       ${c.cyan('runtime prune')}     Preview safe stale-temp cleanup; add --apply to remove
       ${c.cyan('profile init')}      Auto-generate tiered .devcodex/profile/ drafts
       ${c.cyan('profile plan')}      Preview Profile root/tier/file actions without writing
-      ${c.cyan('status')}            Show installed files; add --completion for workflow state
-      ${c.cyan('doctor')}            Diagnose host/agent/mode; add --completion for blockers/actions
+      ${c.cyan('help <command>')}    Show read-only help for one command
+
+    ${c.bold('Advanced commands:')}
+      ${c.cyan('global-adapters')}   Apply user-level host adapters from package root
+      ${c.cyan('grok')}              Launch Grok with the user-global DevCodex kernel
+      ${c.cyan('migrate-layout')}    Plan/apply/rollback centralized .devcodex workspace layout
       ${c.cyan('probe')}             Run bounded local-only diagnostics; accepts IDs and --json
       ${c.cyan('trace show|replay')} Read LocalTaskTrace; trace show --completion reads receipt identities
       ${c.cyan('skill plan')}        Plan a dependency-closed whole-SKILL bundle; add --json for BundleDecisionV2
@@ -1060,27 +1099,18 @@ function buildCliMaintenanceCommands(ctx) {
       ${c.dim('--allow-downgrade')}  (profile init only) Explicitly allow a lower tier; files are retained
       ${c.dim('--json')}             Emit one DevCodexCliEnvelopeV1 document for supported commands
 
-    ${c.bold('Examples:')}
-      devcodex global-adapters apply --dry-run  # R1a: plan user-global adapters from source tree
-      devcodex global-adapters apply            # R1a: refresh user-global adapters without pack/publish
-      npm install -g .                          # R1b: local global install postinstall refresh
-      npm pack && npm install -g ./devcodex-*.tgz  # R2: pre-release tarball
-      npm install -g devcodex                   # R3: published install + postinstall adapters
-      npm update -g devcodex                    # R3: published upgrade + postinstall refresh
-      npm install devcodex                      # Dependency only; prints the required -g guidance
-      devcodex init                             # R4: initialize only this workspace .devcodex
-      devcodex update                           # R4: refresh only this workspace .devcodex
-      devcodex grok                             # Full-evidence Grok launcher using the global kernel
-      devcodex grok -p "Review this diff" --output-format json
-      devcodex migrate-layout plan              # Generate centralized layout migration manifest
-      devcodex runtime status                    # Inspect canonical and legacy runtime state
-      devcodex runtime prune --dry-run           # Preview safe cleanup without writing
-      devcodex profile init --tier profile-standard  # Generate tiered Profile drafts
-      devcodex profile plan --tier profile-closed-loop # Preview a safe upgrade
-      devcodex status                           # Check installation
-      devcodex skill plan intent load-profile --max-bytes 32768 --json
-      devcodex skill resolve my-ws-skill --json
-      devcodex task resolve "my task" --json    # Resolve without loading unrelated task bodies
+    ${c.bold('First use:')}
+      npm install -g devcodex
+      cd <your-project-or-workspace>
+      devcodex init
+      devcodex status
+
+    ${c.bold('Update / uninstall:')}
+      npm update -g devcodex
+      npm uninstall -g devcodex
+
+    Every command supports ${c.cyan('<command> --help')} and ${c.cyan('help <command>')} without writing files.
+    User guide: https://github.com/devcodex-labs/devcodex#readme
   `)
   }
 

scripts/test-cli-command-registry.js

@@ -66,6 +66,15 @@ assert.strictEqual(fakeProcess.exitCode, 0)
 assert.deepStrictEqual(calls.pop(), ['cmdHelp', undefined])
 assert.strictEqual(runCliCommand({ cmd: 'help', argv: [], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger }), 'help')
 assert.deepStrictEqual(calls.pop(), ['cmdHelp', undefined])
+assert.strictEqual(runCliCommand({ cmd: 'help', argv: ['runtime'], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger }), 'help')
+assert.deepStrictEqual(calls.pop(), ['cmdHelp', ['runtime']])
+assert.strictEqual(runCliCommand({ cmd: 'init', argv: ['--help'], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger }), 'help')
+assert.deepStrictEqual(calls.pop(), ['cmdHelp', ['init']])
+assert.ok(!calls.some(call => call[0] === 'cmdInitWorkspaceRuntime'))
+assert.strictEqual(runCliCommand({ cmd: 'profile', argv: ['init', '--help'], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger }), 'help')
+assert.deepStrictEqual(calls.pop(), ['cmdHelp', ['profile', 'init']])
+assert.strictEqual(runCliCommand({ cmd: 'runtime', argv: ['status', '-h'], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger }), 'help')
+assert.deepStrictEqual(calls.pop(), ['cmdHelp', ['runtime', 'status']])
 logs.length = 0
 assert.strictEqual(runCliCommand({ cmd: '--version', argv: [], registry, runMigrateLayout: migrate, process: fakeProcess, c, console: logger, packageVersion: '1.2.3' }), 'version')
 assert.strictEqual(logs.pop(), '1.2.3')

scripts/test-client-contracts.js

@@ -35,6 +35,10 @@ if (evaluatePublicReadmeContract(damagedPublicReadme).valid ||
     )) {
   failures.push('incomplete public README must not bypass legacy consumer checks')
 }
+const missingTaskTutorial = publicReadme.replace('## 常见任务怎么说', '## 任务示例')
+if (evaluatePublicReadmeContract(missingTaskTutorial).valid) {
+  failures.push('public README without the common-task tutorial must fail its contract')
+}
 
 const readAbsolute = createCanonicalAwareReader(ROOT, file => fs.readFileSync(file, 'utf8'))
 const read = file => readAbsolute(path.join(ROOT, file))