@miphamai/cli 0.48.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/mipham/doc-sync.mipham-skill.md

@@ -0,0 +1,198 @@
+---
+name: doc-sync
+description: Keep engineering truth docs aligned with code — map changed code to docs, update stale docs after functional changes, keep git-reviewable
+version: 1.0.0
+---
+
+# Doc Sync
+
+Keep engineering "truth docs" aligned with code. After a functional code change, run this skill to find the docs that map to the changed code, check them against the code + tests, and update anything that drifted. Docs travel with the branch in git and are reviewed alongside the code diff.
+
+## Where truth docs live
+
+Engineering truth docs live under `docs/truth/engineering/`. Routing from code → docs lives in `docs/truth/ROUTES.md`.
+
+```
+docs/truth/
+├── ROUTES.md            # code area → canonical doc mapping
+└── engineering/
+    ├── behaviors/       # implementation behavior
+    ├── contracts/       # API / interface contracts
+    ├── architecture/    # component structure and boundaries
+    ├── workflows/       # multi-step flows and orchestration
+    └── operations/      # runbooks, config, deployment
+```
+
+## Invariants (never break)
+
+- **Doc-only**: touch `docs/truth/**` and `ROUTES.md` only. Never modify functional code, tests, or config outside `docs/truth/`.
+- **Evidence-backed**: every claim cites `file:line` (or `file` for a whole file). No invented behavior.
+- **Branch-scoped**: docs change in the same branch as the code, so they review together.
+
+## Workflow
+
+### 1. Map — find the docs that cover the change
+
+Determine the changed code. Prefer an explicit path argument; otherwise use the working-tree or branch diff:
+
+```bash
+git diff --name-only            # uncommitted working-tree changes
+git diff --name-only HEAD~1     # last commit
+```
+
+Read `docs/truth/ROUTES.md` and match the changed paths to their canonical doc. A route is a glob → doc path pair. A changed path with no route is a signal to create one (Step 3).
+
+### 2. Check — is the doc now stale?
+
+For each mapped doc, read the doc, the changed code, and the relevant tests. Compare:
+
+- Does the doc describe behavior the code no longer has?
+- Does the code add or remove behavior the doc doesn't mention?
+- Do contract shapes (signatures, types, errors) still match?
+- Are the `file:line` evidence pointers still valid?
+
+A doc is stale when any claim no longer matches the code + tests.
+
+### 3. Update — fix the drift
+
+- **Existing doc, stale**: edit the doc in place. Update claims, refresh `file:line` pointers, remove dead behavior, add new behavior. Keep the section structure unless the change demands otherwise.
+- **Existing doc, orphaned**: if the mapped code is gone, remove the doc and its route entry.
+- **Changed path has no route**: create one bounded doc under the right `docs/truth/engineering/<type>/` folder and add a route entry to `ROUTES.md`. Scope the doc to the changed area — do not document the whole codebase.
+
+Keep the diff minimal and reviewable: one doc per functional change, no unrelated rewrites.
+
+### 4. Verify — reviewable and true
+
+Confirm before reporting done:
+
+- `git diff --stat` shows only `docs/truth/**` and `ROUTES.md`.
+- Every claim in the updated doc has a `file:line` pointer that exists in the working tree.
+- The doc matches the code + tests, not the other way around.
+
+Report: "Updated <doc> for <change>. Review the truth diff alongside the code diff."
+
+## Document templates
+
+### Behavior (`behaviors/`)
+
+```markdown
+# <Behavior Name>
+
+**Area**: <route / component>
+**Evidence**: `src/<file>:<line>`
+
+## What it does
+
+<one-paragraph summary, from code + tests>
+
+## Behavior
+
+- <observable behavior> — `src/<file>:<line>`
+
+## Edge cases
+
+- <case> — `src/<file>:<line>`
+
+## Tests
+
+- `tests/<file>.test.ts` — covers <behavior>
+```
+
+### Contract (`contracts/`)
+
+```markdown
+# <API / Interface>
+
+**Evidence**: `src/<file>:<line>`
+
+## Signature
+
+\`\`\`ts
+// the actual exported signature
+\`\`\`
+
+## Parameters
+
+| Param | Type | Description |
+| ----- | ---- | ----------- |
+
+## Returns / Errors
+
+- ...
+
+## Consumers
+
+- <caller> — `src/<file>:<line>`
+```
+
+### Architecture (`architecture/`)
+
+```markdown
+# <Component / Module>
+
+**Evidence**: `src/<file>`
+
+## Responsibility
+
+<one paragraph — what it owns, what it doesn't>
+
+## Dependencies
+
+- depends on: <...>
+- depended on by: <...>
+
+## Boundaries
+
+- <seam / interface> — `src/<file>:<line>`
+```
+
+### Workflow (`workflows/`)
+
+```markdown
+# <Workflow Name>
+
+**Evidence**: `src/<file>:<line>`
+
+## Steps
+
+1. <step> — `src/<file>:<line>`
+
+## Trigger / Exit
+
+- trigger: <...>
+- success: <...> / failure: <...>
+```
+
+### Operations (`operations/`)
+
+```markdown
+# <Runbook / Config>
+
+**Evidence**: `src/<file>`
+
+## Config / Env
+
+| Key | Default | Meaning |
+| --- | ------- | ------- |
+
+## Runbook
+
+- <action> — <command or step>
+
+## Failure modes
+
+- <symptom> → <cause> → <fix>
+```
+
+## Routing file (`ROUTES.md`)
+
+```markdown
+# Truth Routes
+
+| Code pattern      | Doc                                      |
+| ----------------- | ---------------------------------------- |
+| src/auth/session* | engineering/behaviors/session-timeout.md |
+| src/api/*         | engineering/contracts/api.md             |
+```
+
+Patterns are globs relative to the repo root. One doc may be routed by several patterns; one pattern maps to one doc. Keep patterns as specific as needed to avoid one giant doc.

package/skills/mipham/self-audit.mipham-skill.md

@@ -1,6 +1,6 @@
 ---
 name: self-audit
-description: CRSI Phase 2: Mipham Code systematic self-audit — identifies code quality, architecture, performance, and security issues; integrates with CRSI pipeline for auto-rule generation
+description: 'CRSI Phase 2: Mipham Code systematic self-audit — identifies code quality, architecture, performance, and security issues; integrates with CRSI pipeline for auto-rule generation'
 version: 1.0.0
 ---
 

package/skills/standard/web-access/references/cdp-api.md

@@ -0,0 +1,132 @@
+# CDP Proxy API 参考
+
+## 基础信息
+
+- 地址：`http://localhost:3456`
+- 启动：`node ~/.claude/skills/web-access/scripts/cdp-proxy.mjs &`
+- 启动后持续运行，不建议主动停止（重启需 Chrome 重新授权）
+- 强制停止：`pkill -f cdp-proxy.mjs`
+
+## API 端点
+
+### GET /health
+
+健康检查，返回连接状态。
+
+```bash
+curl -s http://localhost:3456/health
+```
+
+### GET /targets
+
+列出所有已打开的页面 tab。返回数组，每项含 `targetId`、`title`、`url`。
+
+```bash
+curl -s http://localhost:3456/targets
+```
+
+### GET /new?url=URL
+
+创建新后台 tab，自动等待页面加载完成。返回 `{ targetId }`.
+
+```bash
+curl -s "http://localhost:3456/new?url=https://example.com"
+```
+
+### GET /close?target=ID
+
+关闭指定 tab。
+
+```bash
+curl -s "http://localhost:3456/close?target=TARGET_ID"
+```
+
+### GET /navigate?target=ID&url=URL
+
+在已有 tab 中导航到新 URL，自动等待加载。
+
+```bash
+curl -s "http://localhost:3456/navigate?target=ID&url=https://example.com"
+```
+
+### GET /back?target=ID
+
+后退一页。
+
+```bash
+curl -s "http://localhost:3456/back?target=ID"
+```
+
+### GET /info?target=ID
+
+获取页面基础信息（title、url、readyState）。
+
+```bash
+curl -s "http://localhost:3456/info?target=ID"
+```
+
+### POST /eval?target=ID
+
+执行 JavaScript 表达式，POST body 为 JS 代码。
+
+```bash
+curl -s -X POST "http://localhost:3456/eval?target=ID" -d 'document.title'
+```
+
+### POST /click?target=ID
+
+JS 层面点击（`el.click()`），POST body 为 CSS 选择器。自动 scrollIntoView 后点击。简单快速，覆盖大多数场景。
+
+```bash
+curl -s -X POST "http://localhost:3456/click?target=ID" -d 'button.submit'
+```
+
+### POST /clickAt?target=ID
+
+CDP 浏览器级真实鼠标点击（`Input.dispatchMouseEvent`），POST body 为 CSS 选择器。先获取元素坐标，再模拟鼠标按下/释放。算真实用户手势，能触发文件对话框、绕过部分反自动化检测。
+
+```bash
+curl -s -X POST "http://localhost:3456/clickAt?target=ID" -d 'button.upload'
+```
+
+### POST /setFiles?target=ID
+
+给 file input 设置本地文件路径（`DOM.setFileInputFiles`），完全绕过文件对话框。POST body 为 JSON。
+
+```bash
+curl -s -X POST "http://localhost:3456/setFiles?target=ID" -d '{"selector":"input[type=file]","files":["/path/to/file1.png","/path/to/file2.png"]}'
+```
+
+### GET /scroll?target=ID&y=3000&direction=down
+
+滚动页面。`direction` 可选 `down`（默认）、`up`、`top`、`bottom`。滚动后自动等待 800ms 供懒加载触发。
+
+```bash
+curl -s "http://localhost:3456/scroll?target=ID&y=3000"
+curl -s "http://localhost:3456/scroll?target=ID&direction=bottom"
+```
+
+### GET /screenshot?target=ID&file=/tmp/shot.png
+
+截图。指定 `file` 参数保存到本地文件；不指定则返回图片二进制。可选 `format=jpeg`。
+
+```bash
+curl -s "http://localhost:3456/screenshot?target=ID&file=/tmp/shot.png"
+```
+
+## /eval 使用提示
+
+- POST body 为任意 JS 表达式，返回 `{ value }` 或 `{ error }`
+- 支持 `awaitPromise`：可以写 async 表达式
+- 返回值必须是可序列化的（字符串、数字、对象），DOM 节点不能直接返回，需要提取属性
+- 提取大量数据时用 `JSON.stringify()` 包裹，确保返回字符串
+- 根据页面实际 DOM 结构编写选择器，不要套用固定模板
+
+## 错误处理
+
+| 错误                        | 原因                       | 解决                                                           |
+| --------------------------- | -------------------------- | -------------------------------------------------------------- |
+| `Chrome 未开启远程调试端口` | Chrome 未开启远程调试      | 提示用户打开 `chrome://inspect/#remote-debugging` 并勾选 Allow |
+| `attach 失败`               | targetId 无效或 tab 已关闭 | 用 `/targets` 获取最新列表                                     |
+| `CDP 命令超时`              | 页面长时间未响应           | 重试或检查 tab 状态                                            |
+| `端口已被占用`              | 另一个 proxy 已在运行      | 已有实例可直接复用                                             |