@zeyue0329/xiaoma-cli 1.17.1-next.0 → 1.19.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.17.1-next.0",
+  "version": "1.19.0",
   "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",

package/src/xmc-skills/1-analysis/xiaoma-project-handover/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: xiaoma-project-handover
+description: 'Produce a new-hire handover manual (HANDOVER.md) for an existing/brownfield project: business data-flow main chains (with sequence diagrams), a complete third-party integration inventory (name/purpose/call style/config location/failure-degradation), design highlights & trade-offs (the "why"), and known pitfalls / traps / legacy debt (weird naming, implicit dependencies, temporary hacks, perf & concurrency risks). Use when the user says "项目交接 / 交接文档 / handover", "onboard a new engineer", "梳理这个项目", or asks how the data flows / what third parties are integrated / where the pitfalls are.'
+---
+
+# Project Handover Workflow
+
+**Goal:** Produce a comprehensive, human-readable handover manual (`HANDOVER.md`) that lets a new engineer take over an unfamiliar project — the tribal knowledge that source code and generic docs do not capture.
+
+**Your Role:** You are a staff engineer running an offboarding/handover session. You read the real code, trace how business data actually flows, catalog every external dependency, explain *why* the system is built the way it is, and write down the traps so the next person does not step on them. You separate verified facts from inferences, and you cite `file:line` for every claim.
+
+## How this differs from `document-project`
+
+`document-project` produces AI-context / brownfield-PRD documentation (architecture.md, api-contracts, data-models, index). This skill produces a **human handover manual** focused on the four things a newcomer most needs and code alone cannot tell them: the end-to-end business flow sequence, the third-party integration map (including failure/degradation behavior), the design rationale and trade-offs, and the known pitfalls / legacy debt. If `document-project` output already exists in `{project_knowledge}/`, **reuse it as input** instead of re-deriving the architecture.
+
+## Conventions
+
+- Bare paths (e.g. `checklist.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:
+
+- `project_name`, `user_name`, `user_skill_level`
+- `communication_language` — for all chat communication
+- `document_output_language` — for all written artifact content
+- `project_knowledge` — output location AND where prior `document-project` artifacts (index.md, architecture.md, …) may already live
+- `date` as system-generated current datetime
+- CLAUDE.md / `**/project-context.md` / README / CONTRIBUTING / docs/ / ADRs (load summaries if they exist)
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+- **If `config.yaml` does not exist** (XiaoMa is not installed in the target, or you are documenting a raw source repo — including XiaoMa's own source): do NOT abort. Fall back to caller-provided runtime parameters or sensible defaults (write output under `{project_knowledge}` or a `docs/` folder; communicate in the user's language), and continue.
+
+### Step 5: Greet the User
+
+Greet `{user_name}` (if you have not already), speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **Write-as-you-go**: Each analysis step writes its section straight into `HANDOVER.md`, then purges the raw findings from context — keep only a one-line summary so long codebases do not exhaust context. (For small/medium codebases you may instead keep findings in context so cross-section references — e.g. a pitfall in §6 citing a flow stage in §3 — stay consistent; the purge is an optimization for large codebases, not a mandate.)
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **NEVER** modify the project's source code — this workflow is read-only over the codebase; it only writes the handover manual under `{project_knowledge}`
+- **ALWAYS** cite evidence as `file:line` (or `file`) for every concrete claim; mark anything you could not verify as an inference to confirm with the original author
+- **ALWAYS** halt at checkpoints and wait for human input — UNLESS autonomous mode is on (see below)
+- **Autonomous / non-interactive mode**: if the caller sets `autonomous = true`, or the trigger explicitly asks to run without stopping (e.g. "自动跑完", "don't stop to ask"), do NOT halt at any CHECKPOINT. Proceed using the best available default (scope = whole project unless specified; chain shortlist = the top candidates you ranked), and record every assumption you made in the final summary instead of asking.
+
+### Optional: parallel deep scans
+
+If your runtime supports launching parallel sub-agents (e.g. a Task tool), you MAY delegate the four deep scans (business flows, third-party integrations, design & trade-offs, pitfalls & legacy) to parallel read-only sub-agents to manage context, then merge their structured findings. This is an optimization, not a requirement — if unavailable, run the steps sequentially with write-as-you-go.
+
+## FIRST STEP
+
+Read fully and follow: `./steps/step-01-scope-and-orient.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/checklist.md

@@ -0,0 +1,68 @@
+# Project Handover — Validation Checklist
+
+Run this before declaring the handover manual complete. Every box must be checked or explicitly waived with a reason recorded in section 10 (Open Questions).
+
+## Coverage of the four required pillars
+
+### Business data-flow main chains (section 3)
+
+- [ ] At least the 3 most important business main chains are documented (not just one)
+- [ ] Each chain names its trigger (HTTP / MQ / scheduled job / callback) with `file:line`
+- [ ] Each chain has a Mermaid sequence diagram covering entry → service → rules → persistence → external/writeback
+- [ ] Each chain has a stage table (stage / entry / key class·method / input / processing / output·state-change / persistence / failure handling)
+- [ ] Sync vs async hops (MQ / thread pool) are distinguished
+- [ ] Transaction boundaries, idempotency keys, and compensation/rollback are noted where they exist
+- [ ] State machines / status enums are documented where present
+
+### Third-party integration inventory (section 4)
+
+- [ ] Dependency manifests were scanned (package.json / pom.xml / build.gradle / go.mod / requirements.txt / Gemfile, etc.)
+- [ ] HTTP/RPC clients and middleware (DB, cache, MQ, object storage, config/registry center, search, monitoring) are all included
+- [ ] For EVERY integration: name, purpose, call style, key client class, config location (file:key), auth, and **failure-degradation behavior** are filled — no blanks
+- [ ] Failure handling explicitly states retry / circuit-breaker / fallback / degrade / none for each integration
+- [ ] An "environment & secrets" note tells a new dev what is needed to run locally and where secrets live
+
+### Design highlights & trade-offs (section 5)
+
+- [ ] Key design decisions / patterns / extension points are listed (not just "uses Spring")
+- [ ] Each entry explains the problem it solves AND why it was chosen AND what was traded off
+- [ ] Each entry is marked as verified (doc/comment/ADR/commit) vs inferred (needs author confirmation)
+
+### Known pitfalls & legacy debt (section 6)
+
+- [ ] Marker scan was run (TODO / FIXME / HACK / XXX / @Deprecated / workaround / 临时 / 兼容 / 历史 / 慎改 / 坑)
+- [ ] At least the categories present in the code are covered: traps, implicit dependencies, temporary hacks, perf/concurrency, weird naming, legacy
+- [ ] Each pitfall has location, symptom/risk, trigger condition, how-to-avoid, and severity
+
+## Newcomer usability
+
+- [ ] Section 1 (Orientation) lets a stranger build a mental model and run the project
+- [ ] Section 2 (Module map) answers "to change feature X, which module do I touch?"
+- [ ] Section 7 (Glossary) defines the non-obvious terms / abbreviations / status codes / table names used in the doc
+- [ ] Section 8 (Onboarding checklist) gives concrete first steps including a starter task
+- [ ] Section 9 (Troubleshooting pointers) maps common symptoms to where to look first
+
+## Evidence & honesty
+
+- [ ] Concrete claims cite `file:line` (or `file`) — not vague generalities
+- [ ] Inferences are clearly flagged with the ⚠️ marker and collected in section 10 (Open Questions)
+- [ ] No fabricated APIs, tables, or integrations — only what exists in the code
+
+## Output hygiene
+
+- [ ] HANDOVER.md written to `{project_knowledge}/`
+- [ ] No leftover `<!-- FILL` markers remain in the final document
+- [ ] No template comment blocks (the single-chain template, etc.) remain
+- [ ] Mermaid diagrams are syntactically valid (render-checkable) — no raw `<` `>` `{` `}` in diagram message text (they break the parser; use plain words like `applyNo`)
+- [ ] Document is written in `{document_output_language}`
+- [ ] Markdown renders cleanly (tables aligned, code fences closed)
+
+## Completion criteria
+
+The handover manual is complete when:
+
+1. All four required pillars (sections 3–6) are concrete and non-empty
+2. Every integration row has a failure-degradation value
+3. No `<!-- FILL` markers or template scaffolding remain
+4. Inferences are flagged and gathered in Open Questions
+5. The user has reviewed and confirmed the manual is usable for onboarding

package/src/xmc-skills/1-analysis/xiaoma-project-handover/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for xiaoma-project-handover. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per XiaoMa structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (handover conventions, in-house terminology, compliance constraints).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All third-party calls must document their failure-degradation behavior."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/glossary.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its terminal stage, after
+# the main output has been delivered. Override wins. Leave empty for
+# no custom post-completion behavior.
+
+on_complete = ""

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-01-scope-and-orient.md

@@ -0,0 +1,89 @@
+---
+scope: '' # set at runtime: "whole-project" | "module:<path>" | "flow:<name>"
+output_dir: '' # set at runtime: resolved {project_knowledge}
+handover_doc: '' # set at runtime: {output_dir}/HANDOVER.md
+git_ref: '' # set at runtime: current commit / "no-vcs"
+priority_flows: '' # set at runtime: business flows the user wants prioritized
+autonomous: false # set true by the caller to auto-proceed at every CHECKPOINT without halting
+---
+
+> These frontmatter fields are **in-memory working variables** for this run. There is no file to write them back to — carry their values forward across steps in context. `autonomous` may be set by the caller (or inferred from a "run without stopping" trigger).
+
+# Step 1: Scope & Orient
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- This whole workflow is **read-only over the project's source code**. You only write the handover manual under `{project_knowledge}`.
+- The prompt that triggered this workflow IS the intent — treat any path / module / flow named in it as the scope, do not re-ask if it is already clear.
+- Cite `file:line` for concrete claims. This step only builds the map; the deep passes come later.
+
+## INSTRUCTIONS
+
+### 1. Resolve output location and baseline
+
+1. Set `{output_dir}` = resolved `{project_knowledge}`. Set `{handover_doc}` = `{output_dir}/HANDOVER.md`.
+2. If `{handover_doc}` already exists, ask the user: **overwrite / start fresh** or **cancel**. Do not silently clobber prior work.
+3. Capture `{git_ref}`: if a Git repo, run `git rev-parse --short HEAD` and `git symbolic-ref --short HEAD` (or note detached HEAD). If no VCS, set `{git_ref}` = `"no-vcs"`.
+
+### 2. Determine scope
+
+Determine `{scope}` from the triggering prompt and recent conversation. If still ambiguous: when `{autonomous}` is false, HALT and ask the user to pick; when `{autonomous}` is true, default to **whole project** and record the assumption for the final summary. The choices:
+
+- **Whole project** — handover for the entire codebase
+- **A module / subsystem / path** — handover scoped to one area (ask for the path)
+- **A specific business flow** — center the handover on one named flow (e.g. "对账", "受理")
+
+Also ask (one combined question, skip what the prompt already answered; skip entirely if `{autonomous}` is true):
+
+- Any **business flows to prioritize**? (store as `{priority_flows}`) — e.g. 业务受理、规则校验、对账、回写
+- Who is the **audience** — a new team member, or an external/outgoing handover? (tunes how much in-house context to spell out)
+
+### 3. Reuse what already exists (do NOT re-derive)
+
+Scan for and load *summaries* of prior knowledge so you build on it instead of redoing architecture work:
+
+- `document-project` output in `{output_dir}`: `index.md`, `project-overview.md`, `architecture*.md`, `source-tree-analysis.md`, `data-models*.md`, `api-contracts*.md`
+- `README*`, `CONTRIBUTING*`, `docs/`, `ARCHITECTURE*`, ADRs (`docs/adr/`, `doc/decisions/`), `CHANGELOG*`
+- `**/project-context.md`, `CLAUDE.md`, in-repo wikis
+
+Keep only a one-paragraph summary of each in context. If `architecture.md` exists, treat its tech-stack/topology as given and move faster.
+
+### 4. Orient: build the map (lightweight, no deep tracing yet)
+
+Establish the skeleton the later passes will hang off:
+
+- **Tech stack:** detect languages, frameworks, ORM/data layer, build tool, runtime, key versions — from manifests (`package.json`, `pom.xml`, `build.gradle`, `go.mod`, `requirements.txt`, `Gemfile`, `*.csproj`) and lockfiles.
+- **How to run:** install / start / build / test commands (from manifests, scripts, README, Makefile, Dockerfile, compose).
+- **Entry points / external-comm surfaces** (these seed Step 2): controllers/routes, RPC/gRPC services, MQ consumers/listeners, scheduled jobs/cron, CLI commands, webhook/callback receivers, event handlers, app bootstrap/main.
+- **Data stores:** primary/replica DBs, cache, message broker, object storage, search — from config + client wiring.
+- **Module responsibility map:** top-level modules/packages/services, each with its responsibility, key directory, exposed surface, and main dependencies. A Mermaid `graph LR` of module dependencies is welcome.
+- **Glossary seed:** start a running list of non-obvious terms / abbreviations / status enums / table names you encounter (carried forward to Step 6).
+
+Use glob/grep and read only the files needed to map the above — do NOT exhaustively read source yet.
+
+### 5. Create the handover skeleton
+
+1. Read `../templates/handover-template.md`.
+2. Substitute the top-matter variables (`{{project_name}}`, `{{date}}`, `{{scope}}`, `{{user_name}}`, `{{git_ref}}`).
+3. Fill **Section 1 (Orientation)** and **Section 2 (Module Responsibility Map)** now, from step 4 above. Write real content in `{document_output_language}`. Keep the template's bilingual section headers as-is — only the body content you author follows `{document_output_language}`.
+4. Leave the `<!-- FILL: ... -->` markers for sections 3–11 in place (later steps fill them).
+5. Write the result to `{handover_doc}`.
+
+## CHECKPOINT
+
+Present to the user, in `{communication_language}`:
+
+- Resolved scope, output path, and code baseline
+- The detected tech stack + how-to-run
+- The module responsibility map (table or list)
+- The list of candidate entry points you will trace in Step 2, and which flows are prioritized
+
+If `{autonomous}` is false: HALT and ask the user to confirm or correct the scope, module map, and priority flows before proceeding; incorporate corrections into `{handover_doc}` sections 1–2.
+
+If `{autonomous}` is true: skip the HALT — proceed with the detected scope and map, and note any assumptions for the Step 6 summary.
+
+## NEXT
+
+Read fully and follow `./step-02-business-flows.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-02-business-flows.md

@@ -0,0 +1,69 @@
+---
+main_chains: '' # set at runtime: the 3-7 prioritized business chains being traced
+---
+
+# Step 2: Business Data-Flow Main Chains
+
+Fill **Section 3** of `{handover_doc}`: trace how business data actually moves through the system, end to end.
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- Read-only over source code. Cite `file:line` for every entry/stage you describe.
+- Trace what the code **actually does**, not what names suggest. If a hop is async or its target is unclear, say so rather than inventing a clean path.
+
+## INSTRUCTIONS
+
+### 1. Enumerate and cluster entry points
+
+Start from the entry points found in Step 1. Make sure you have covered every kind:
+
+- HTTP controllers / routes / REST handlers
+- RPC / gRPC service implementations
+- MQ consumers / listeners / subscribers (Kafka, RocketMQ, RabbitMQ, Pulsar, …)
+- Scheduled jobs / cron / `@Scheduled` / quartz / xxl-job
+- CLI commands, batch jobs
+- Webhook / callback receivers (payment notify, third-party push-back)
+- Event handlers / domain-event listeners / state-machine transitions
+
+Cluster them into **business capabilities** (e.g. 受理 / 审核 / 复核 / 回写 / 对账 / 通知 / 退款). 
+
+### 2. Pick the main chains
+
+Select the **3–7 most important end-to-end chains**. Prefer `{priority_flows}` if the user named any. Otherwise rank by: appears in README/docs, central tables touched, volume/criticality implied by naming, breadth of code it pulls in. If unsure which to include and `{autonomous}` is false, HALT and ask the user to confirm the shortlist; if `{autonomous}` is true, auto-select the top-ranked chains and note the choice in the final summary.
+
+### 3. Trace each chain end to end
+
+For each main chain, follow the call path through the layers:
+
+`entry (controller/consumer/job) → application/service → domain logic / rule engine → repository/persistence → external calls → response / callback / writeback`
+
+While tracing, capture for each hop:
+
+- **Sync vs async** — direct call, vs handed to a thread pool / MQ / scheduled retry. Mark every async boundary explicitly.
+- **Transaction boundaries** — where a DB transaction opens/commits; whether external calls happen inside it (a classic trap).
+- **Idempotency** — idempotency keys, dedup tables, unique constraints.
+- **State changes** — which status field/enum moves from what to what, and where it persists.
+- **Failure path** — what happens on error at each stage: throw / retry / compensate / rollback / dead-letter / manual-review queue.
+- **Branching** — significant conditional routes (e.g. auto-pass vs route-to-human-review).
+
+### 4. Write the section
+
+For each chain, emit a `### 3.x <chain name>` subsection containing:
+
+1. One-line TL;DR + trigger (`file:line`) + sync/async note.
+2. A **Mermaid `sequenceDiagram`** of the main path (participants = the real classes/components via `as` aliases; arrows = the real calls; use `-->>` for returns; mark async hops; `alt/else/end` for the key failure branch). **Diagram text must avoid raw `<`, `>`, `{`, `}`** — they break the Mermaid parser; replace any placeholder like `<id>` with plain words (e.g. `applyNo`). Keep it readable: main path plus the most important failure branch.
+3. A **stage table**: 阶段 | 入口/触发 | 关键类·方法 (file:line) | 输入数据 | 处理/规则 | 产出/状态变更 | 落库(表/缓存) | 失败处理. Add **one row per REAL stage** — do not pad to a fixed set. If a stage you expect (e.g. 人工复核) actually happens **outside this codebase** (e.g. only a consumer of an externally-produced message exists), say so with ⚠️ rather than inventing an internal stage.
+4. State machine / status enum block if the flow has one (`file:line`).
+5. Idempotency / transaction / compensation note.
+
+Replace the `<!-- FILL: business-flows -->` marker in `{handover_doc}` with the rendered chains. **Edit the file now** — do not hold the content only in memory.
+
+### 5. Purge
+
+After writing, drop the raw trace details from working context. Keep only a one-line summary per chain (name + the tables/externals it touches) to carry forward.
+
+## NEXT
+
+Read fully and follow `./step-03-third-party-integrations.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-03-third-party-integrations.md

@@ -0,0 +1,64 @@
+# Step 3: Third-Party Integration Inventory
+
+Fill **Section 4** of `{handover_doc}`: an exhaustive map of everything external the system depends on, with special attention to **failure-degradation behavior**.
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- Read-only over source code. Only list integrations that actually exist in the code/config — never invent one.
+- "Third party" = external business SDKs, remote HTTP/RPC services, AND middleware that is external from a handover standpoint (DB, cache, MQ, object storage, config/registry center, search, monitoring). Include all of them.
+
+## INSTRUCTIONS
+
+### 1. Detect — scan these sources
+
+**Dependency manifests** (the fastest signal): `package.json`, `pom.xml`, `build.gradle(.kts)`, `go.mod`, `requirements.txt` / `pyproject.toml`, `Gemfile`, `*.csproj`, `composer.json`. Flag any dependency that talks to the outside world.
+
+**Common integration categories to look for** (names vary by region/vendor):
+
+- 支付/收银 payment, 银行/银联/网银 bank, 发票 invoice
+- 短信 SMS, 邮件 email, 推送 push, IM/客服, 语音/呼叫
+- 对象存储 OSS/COS/S3/MinIO, CDN
+- 实名/认证 KYC, 风控 risk-control, 征信, OCR, 人脸 face, 电子签 e-sign
+- 地图/定位 map, 天气, 翻译
+- 登录/SSO/OAuth, 企业微信/钉钉/飞书, 微信/支付宝开放平台
+- 消息队列 MQ (Kafka/RocketMQ/RabbitMQ/Pulsar), 缓存 Redis/Memcached, 搜索 ES/OpenSearch
+- 数据库 RDBMS/NoSQL, 配置中心 Nacos/Apollo/Consul, 注册中心/服务发现, 网关
+- 监控/APM/链路 (Prometheus/SkyWalking/Sentry/CAT), 日志采集, 大数据/数仓上报
+- LLM/AI 服务, 任意内部"中台"/平台服务
+
+**Code-level signals:**
+
+- HTTP clients: `RestTemplate`, `WebClient`, `OkHttp`, `HttpClient`, `Feign`/`@FeignClient`, `axios`, `fetch`, `requests`, base URLs, `*Client`/`*Api`/`*Adapter`/`*Connector`/`*Gateway` classes.
+- RPC stubs: gRPC/Dubbo/Thrift service references, `@DubboReference`.
+- SDK init: client/builder construction with appId/appKey/accessKey/endpoint.
+- Connection wiring: datasource/redis/mq/es client configuration beans.
+
+**Config signals:** grep config files (`application*.yml|properties`, `*.env`, `.env*`, `appsettings*.json`, `config/*`) and config-center keys for: `url|host|endpoint|appid|app-key|access-key|ak|sk|secret|token|account|merchant|dsn|brokers|bootstrap-servers|nameserver`.
+
+### 2. For each integration, fill every column
+
+No blanks. Each row must have:
+
+- **名称 Name** — the service/vendor/middleware
+- **类别 Category** — payment / sms / mq / cache / db / config-center / monitoring / …
+- **用途 Purpose** — the business scenario it serves (tie back to Step 2 flows where relevant)
+- **调用方式 Call style** — SDK / HTTP / RPC / MQ produce·consume / JDBC / driver
+- **关键客户端 Key client** — the class/module that owns the call (`file`)
+- **配置位置 Config location** — exact file + key(s)
+- **鉴权 Auth** — appId/secret, AK/SK, token, mTLS, none
+- **失败降级 Failure handling** ← the important one: state explicitly whether there is **retry** (how many / backoff), **circuit breaker** (Sentinel/Hystrix/Resilience4j), **fallback / degrade** (default value, cache, skip), **bulkhead/timeout**, **dead-letter / manual-review**, or **none (error propagates)**. If you cannot find any handling, write "无显式降级(异常直接抛出)" — do not leave it implied.
+- **风险备注 Risk** — single point of failure, prod-only, tight coupling, etc.
+
+### 3. Environment & secrets note (section 4.1)
+
+Summarize what a new dev needs to run the project locally/in test: which integrations are required vs optional, where secrets live (env vars / config center / vault / committed-and-must-rotate), and which third parties offer a sandbox/mock vs are production-only.
+
+### 4. Write + purge
+
+Replace the `<!-- FILL: third-parties -->` and `<!-- FILL: 4.1 -->` markers in `{handover_doc}` with the inventory table + environment note. **Edit the file now.** Then purge raw findings, keeping only a count + the list of integration names.
+
+## NEXT
+
+Read fully and follow `./step-04-design-and-tradeoffs.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-04-design-and-tradeoffs.md

@@ -0,0 +1,36 @@
+# Step 4: Design Highlights & Trade-offs
+
+Fill **Section 5** of `{handover_doc}`: explain *why* the system is built the way it is, so the new owner does not unknowingly undo a deliberate decision.
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- Read-only over source code. Cite `file:line` for where each design lives.
+- **Separate verified from inferred.** A rationale stated in a doc/comment/ADR/commit is verified. A rationale you reconstructed from the code shape is an inference — mark it `⚠️ 推断` and add it to Open Questions in Step 6.
+
+## INSTRUCTIONS
+
+### 1. Gather the rationale signals
+
+- **Explicit sources:** ADRs (`docs/adr/`, `doc/decisions/`), design docs, README "design/决策/架构" sections, rich code comments, and `git log` messages on large refactors/feature commits (`git log --oneline -- <path>` on key modules).
+- **Structural signals (infer the "why" from the "what"):** layering & module boundaries, key abstractions and extension points (interfaces, SPI, plugin registries, strategy/factory/template-method/state-machine/observer patterns), async decoupling (MQ, event bus, thread pools), caching strategy, idempotency & dedup design, sharding / partitioning / read-write split, distributed lock, rate limiting / circuit breaking, config-driven behavior & feature flags, consistency choices (eventual vs strong, saga/TCC), API/versioning strategy.
+
+### 2. For each highlight / decision, capture
+
+- **决策 Decision / 亮点 Highlight** — what it is
+- **位置 Where** — module/class (`file:line`)
+- **解决的问题 Problem** — what pain it addresses
+- **为什么这样设计 Rationale** — the reasoning
+- **取舍/代价 Trade-off** — what was given up (complexity, latency, consistency, cost, coupling), and any alternative that was rejected if you can tell
+- **来源 Source** — `确证` (cite the doc/comment/commit) or `⚠️ 推断`
+
+Focus on decisions a newcomer could plausibly break or "simplify" by accident (the non-obvious-on-purpose ones). Skip boilerplate framework defaults that carry no real decision.
+
+### 3. Write + purge
+
+Replace the `<!-- FILL: design -->` marker in `{handover_doc}` with the table. **Edit the file now.** Collect every `⚠️ 推断` item to carry into Step 6's Open Questions. Then purge raw detail, keeping only the list of decision titles.
+
+## NEXT
+
+Read fully and follow `./step-05-pitfalls-and-legacy.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-05-pitfalls-and-legacy.md

@@ -0,0 +1,42 @@
+# Step 5: Known Pitfalls & Legacy Debt
+
+Fill **Section 6** of `{handover_doc}`: the traps a newcomer will step on that nobody writes down.
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- Read-only over source code. Cite `file:line` for every pitfall.
+- Prefer concrete, located traps over generic advice. "This loop calls a remote API per row (`Foo.java:88`)" beats "watch out for performance".
+
+## INSTRUCTIONS
+
+### 1. Run the marker scan
+
+Grep the codebase (case-insensitive) for: `TODO`, `FIXME`, `HACK`, `XXX`, `@Deprecated` / `deprecated`, `workaround`, `临时`, `兼容`, `历史`, `先这样` / `暂时`, `不要动` / `慎改` / `勿删`, `坑`, `注意` / `特别注意`, `magic`, `tricky`. Each hit is a lead — read around it and decide if it is handover-worthy.
+
+### 2. Hunt each category
+
+- **Implicit dependencies (隐式依赖):** order-dependent initialization, global/static mutable state, `ThreadLocal`, reliance on system time / timezone / locale / default charset, hardcoded IDs / paths / enum values, hidden coupling between modules, DB triggers / stored procedures, cross-service shared tables, classpath/bean load order, environment-specific assumptions.
+- **Temporary solutions (临时方案):** hardcoded switches, feature flags left permanently on/off, commented-out code kept "just in case", dual-write / 双写, grayscale/灰度 leftovers, "v2" code paths running beside "v1".
+- **Performance / concurrency risks:** N+1 queries, remote calls inside loops, missing pagination, unbounded caches / collections, non-idempotent retries, race conditions, lock granularity / lock ordering / deadlock risk, thread-pool sizing & rejection policy, large transactions holding locks, slow SQL / missing indexes, sync calls on hot paths.
+- **Weird naming (命名怪异):** misleading names, 拼音 or cryptic abbreviations, status codes / enums whose numeric meaning is non-obvious, table/field names that do not match their actual content, names that contradict behavior.
+- **Legacy debt (历史遗留):** dead code, abandoned modules, outdated/vulnerable dependencies, deprecated APIs still in use, migrations half-done.
+- **Git heat (optional, if VCS):** `git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head` to find churn-hot files, and scan for revert-heavy areas — frequently-changed files often hide fragility worth flagging.
+
+### 3. For each pitfall, capture
+
+- **类型 Type** — `坑/反直觉` / `隐式依赖` / `临时方案` / `性能/并发` / `命名怪异` / `历史遗留`
+- **位置 Location** — `file:line`
+- **现象/风险 Symptom & risk** — what goes wrong
+- **触发条件 Trigger** — when it bites (high load, specific input, certain order, off-by-timezone, …)
+- **规避/正确做法 How to avoid** — what the newcomer should do instead
+- **严重度 Severity** — 高 / 中 / 低
+
+### 4. Write + purge
+
+Replace the `<!-- FILL: pitfalls -->` marker in `{handover_doc}` with the table, sorted by severity (高 first). **Edit the file now.** Then purge raw findings, keeping only counts by severity.
+
+## NEXT
+
+Read fully and follow `./step-06-assemble-handover.md`

package/src/xmc-skills/1-analysis/xiaoma-project-handover/steps/step-06-assemble-handover.md

@@ -0,0 +1,58 @@
+# Step 6: Assemble & Validate the Handover Manual
+
+Fill the remaining sections, validate, and finalize `{handover_doc}`.
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
+- Read-only over source code.
+
+## INSTRUCTIONS
+
+### 1. Fill the supporting sections
+
+Using context accumulated across Steps 1–5, fill the remaining `<!-- FILL -->` markers in `{handover_doc}`:
+
+- **Section 7 — 术语表 / Glossary:** the running glossary seeded in Step 1 plus every non-obvious term, abbreviation, status enum, and key table name used elsewhere in the manual. A newcomer should be able to resolve any jargon in the doc here.
+- **Section 8 — 新人上手清单 / Onboarding Checklist:** concrete, ordered, checkable steps — clone & install & configure, run locally/in test, walk one main chain from Section 3, then a real **starter task** suitable for a newcomer, plus how to find each key module's owner.
+- **Section 9 — 出问题先看哪里 / Troubleshooting Pointers:** common symptoms → first place to look (which log / monitor / table / switch). Pull from the failure paths in Section 3 and the integrations in Section 4.
+- **Section 10 — 待确认问题 / Open Questions:** gather every `⚠️ 推断` item from Steps 2–5, plus information gaps and anything needing the original author/owner to confirm.
+- **Section 11 — 参考资料 / References:** README, architecture docs, ADRs, prior `document-project` output, API docs, monitoring dashboards, wikis, related repos.
+
+**Edit the file** to replace each marker.
+
+### 2. Validate against the checklist
+
+Run `../checklist.md` against `{handover_doc}`. Pay special attention to:
+
+- All four required pillars (Sections 3–6) are concrete and non-empty.
+- **Every** integration row in Section 4 has a failure-degradation value (no blanks).
+- No `<!-- FILL` markers and no template scaffolding (the single-chain template comment, etc.) remain anywhere in the file.
+- Concrete claims cite `file:line`; inferences are flagged and live in Open Questions.
+- Mermaid diagrams are syntactically valid.
+
+Fix anything that fails before continuing. If a required pillar is genuinely empty because the codebase has nothing of that kind (e.g. zero third parties), state that explicitly in the section rather than leaving a marker.
+
+### 3. Final summary
+
+Present to the user, in `{communication_language}`:
+
+- Path: `{handover_doc}`
+- A short table of contents with one-line status per section (e.g. "业务主链路: 5 条", "三方: 12 个", "已知坑: 8 条(高 2)")
+- The count of Open Questions that need author confirmation
+- Any checklist items that could not be satisfied, and why
+
+### 4. Offer next actions
+
+If `{autonomous}` is true, skip this offer and finalize directly. Otherwise ask whether the user wants to:
+
+1. **Deep-dive** a specific business chain, integration, or module (re-run the relevant pass at higher depth on that target)
+2. **Add** a section the team needs (e.g. release/rollback runbook, on-call guide)
+3. **Finalize** (done)
+
+Loop on the user's choice until they finalize.
+
+### 5. On complete
+
+When finalized, run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow.on_complete` — if the resolved value is non-empty, follow it as the final terminal instruction before exiting. **If the script fails or `_xiaoma` is absent** (e.g. XiaoMa is not installed in the target), skip this step and treat `on_complete` as empty.

package/src/xmc-skills/1-analysis/xiaoma-project-handover/templates/handover-template.md

@@ -0,0 +1,132 @@
+# {{project_name}} — 项目交接手册 (Project Handover)
+
+> 面向新接手工程师的交接文档。目标：读完即可独立定位代码、看懂业务怎么跑、知道接了哪些三方、明白为什么这么设计、避开已知的坑。
+> A handover manual for the engineer taking over. After reading it you should be able to navigate the code, understand how the business actually runs, know every external dependency, understand the design rationale, and avoid the known traps.
+
+- **交接范围 / Scope:** {{scope}}
+- **生成日期 / Date:** {{date}}
+- **整理人 / Prepared by:** {{user_name}}
+- **代码基线 / Code baseline:** {{git_ref}}
+- **证据约定 / Evidence:** 每条具体结论尽量标注 `文件:行号`；无法验证的标注「⚠️ 推断，需与原作者确认」。
+
+---
+
+## 1. 速览 / Orientation
+
+<!-- FILL: orientation — 用 5~10 句话让新人建立心智模型：这个系统是做什么的、属于什么类型(Web/后端服务/批处理/网关...)、核心业务名词、技术栈(语言/框架/构建/运行时)、如何本地跑起来(关键命令)、代码入口在哪。给出"如果你只读一处，先读这里"的指引。 -->
+
+| 维度 Dimension | 内容 |
+| --- | --- |
+| 系统定位 What it is | <!-- FILL --> |
+| 技术栈 Tech stack | <!-- FILL: 语言/框架/ORM/构建工具/运行时 + 版本 --> |
+| 运行方式 How to run | <!-- FILL: 安装/启动/构建/测试 关键命令 --> |
+| 代码入口 Entry points | <!-- FILL: main/启动类/路由注册/消费者注册 file:line --> |
+| 数据存储 Data stores | <!-- FILL: 主库/从库/缓存/消息/对象存储/搜索 --> |
+| 配置位置 Config | <!-- FILL: 配置文件/环境变量/配置中心 路径 --> |
+
+---
+
+## 2. 关键模块责任地图 / Module Responsibility Map
+
+<!-- FILL: module-map — 列出顶层模块/包/服务，每个一行：负责什么、关键目录、对外暴露面(接口/消费者/任务)、依赖了谁。让新人知道"改 X 功能去哪个模块"。可附一张 mermaid 模块依赖图(graph LR)。 -->
+
+| 模块 Module | 职责 Responsibility | 关键目录/类 Path | 对外暴露 Surface | 主要依赖 Depends on |
+| --- | --- | --- | --- | --- |
+| <!-- FILL --> | | | | |
+
+---
+
+## 3. 业务数据流转主链路 / Business Data-Flow Main Chains ★
+
+> 这是新人最需要、代码最难一眼看清的部分：业务数据从进入系统到落地，到底经过哪些阶段、谁触发、在哪处理、写到哪、失败了怎么办。
+
+<!-- FILL: business-flows -->
+
+<!-- 结构由 step-02 提供：每条主链路一个 `### 3.x <名称>` 小节 = TL;DR + 触发(file:line) + 同步/异步 + mermaid sequenceDiagram(图内勿用裸 <>/{}) + 阶段表(按真实链路增删行) + 状态机 + 幂等/事务/补偿。填充时把本说明一并删除。 -->
+
+---
+
+## 4. 三方接入清单 / Third-Party Integration Inventory ★
+
+> "三方"包含：外部业务/平台 SDK、HTTP/RPC 远程服务，以及从交接视角同样属于外部依赖的中间件(数据库、缓存、消息队列、对象存储、配置/注册中心、搜索、监控等)。
+
+<!-- FILL: third-parties — 穷尽扫描所有外部依赖(见 step-03 的探测目录)。每个依赖一行，必须覆盖：名称、用途、调用方式、关键客户端类、配置位置(文件+key)、鉴权方式、失败降级行为。失败降级是重点：有没有重试/熔断/降级/兜底，还是直接抛？ -->
+
+| 名称 Name | 类别 Category | 用途/业务场景 Purpose | 调用方式 Call style | 关键客户端 (file) | 配置位置 (文件:key) | 鉴权 Auth | 失败降级 Failure handling | 风险备注 Risk |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| <!-- FILL --> | | | | | | | | |
+
+### 4.1 环境与密钥 / Environment & secrets
+
+<!-- FILL: 新人本地/测试环境跑通需要哪些外部依赖与密钥？密钥存放在哪(env / 配置中心 / vault)？哪些三方有沙箱/mock 可用，哪些只有生产？ -->
+
+---
+
+## 5. 设计亮点与权衡 / Design Highlights & Trade-offs ★
+
+> 解释"为什么这么设计"，让新人不会无意中破坏掉有意为之的设计。
+
+<!-- FILL: design — 列出关键设计决策/亮点：用了什么模式/抽象/扩展点(策略/工厂/模板方法/状态机/SPI/异步解耦/缓存/分库分表/幂等/分布式锁/限流...)、解决什么问题、为什么这样选、放弃了什么(代价)。区分"确证"(来自文档/注释/ADR/commit)与"推断"(从代码反推，需确认)。 -->
+
+| 亮点/决策 Decision | 位置 Where | 解决的问题 Problem | 为什么这样设计 Rationale | 取舍/代价 Trade-off | 来源 Source(确证/推断) |
+| --- | --- | --- | --- | --- | --- |
+| <!-- FILL --> | | | | | |
+
+---
+
+## 6. 已知坑与历史遗留 / Known Pitfalls & Legacy Debt ★
+
+> 新人最容易踩雷、且没人会主动告诉你的地方：命名怪异、隐式依赖、临时方案、性能/并发风险、历史遗留。
+
+<!-- FILL: pitfalls — 见 step-05 的探测手法(标记词/隐式依赖/临时方案/性能并发/命名/git 热点)。每条一行，给出位置、现象/风险、触发条件、规避/正确做法、严重度。 -->
+
+| 类型 Type | 位置 (file:line) | 现象/风险 Symptom & risk | 触发条件 Trigger | 规避/正确做法 How to avoid | 严重度 Severity |
+| --- | --- | --- | --- | --- | --- |
+| <!-- FILL --> | | | | | |
+
+类型取值：`坑/反直觉` `隐式依赖` `临时方案` `性能/并发` `命名怪异` `历史遗留`。
+
+---
+
+## 7. 术语表 / Glossary
+
+<!-- FILL: glossary — 业务与代码里出现的非显而易见的名词、缩写、拼音、状态码/枚举含义、关键表名释义。让新人看代码不再一头雾水。 -->
+
+| 术语 Term | 含义 Meaning | 出现位置 Where |
+| --- | --- | --- |
+| <!-- FILL --> | | |
+
+---
+
+## 8. 新人上手清单 / Onboarding Checklist
+
+<!-- FILL: onboarding -->
+<!-- 渲染为可勾选清单(- [ ] ...):环境搭建 → 跑起来 → 跑通一条主链路 → 一个练手小任务 → 关键负责人/owner。填充时删除本说明。 -->
+
+---
+
+## 9. 出问题先看哪里 / Troubleshooting Pointers
+
+<!-- FILL: troubleshooting — 常见问题/告警 → 先看哪个日志/监控/表/开关。链路出问题时的排查顺序。 -->
+
+| 症状 Symptom | 先看哪里 Where to look first |
+| --- | --- |
+| <!-- FILL --> | |
+
+---
+
+## 10. 待确认问题 / Open Questions
+
+<!-- FILL: open-questions -->
+<!-- 渲染为可勾选清单:汇总所有「⚠️ 推断」结论、信息缺口、需找原作者/owner 确认的点。填充时删除本说明。 -->
+
+---
+
+## 11. 参考资料 / References
+
+<!-- FILL: references -->
+<!-- 列表:已有文档(README/架构图/ADR/document-project 产出/接口文档/监控面板/wiki)、相关仓库、关键链接。填充时删除本说明。 -->
+
+---
+
+_Generated using the XiaoMa Method `xiaoma-project-handover` workflow._

package/src/xmc-skills/module-help.csv

@@ -1,6 +1,7 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 XiaoMa Method,_meta,,,,,,,,,false,,
 XiaoMa Method,xiaoma-document-project,Document Project,DP,Analyze an existing project to produce useful documentation.,,,anytime,,,false,project-knowledge,*
+XiaoMa Method,xiaoma-project-handover,Project Handover,HO,Analyze an existing project and produce a new-hire handover manual: business data-flow main chains third-party integrations design trade-offs and known pitfalls.,,,anytime,,,false,project-knowledge,handover manual
 XiaoMa Method,xiaoma-generate-project-context,Generate Project Context,GPC,Scan existing codebase to generate a lean LLM-optimized project-context.md. Essential for brownfield projects.,,,anytime,,,false,output_folder,project context
 XiaoMa Method,xiaoma-quick-dev,Quick Dev,QQ,Unified intent-in code-out workflow: clarify plan implement review and present.,,,anytime,,,false,implementation_artifacts,spec and project implementation
 XiaoMa Method,xiaoma-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal