@fateforge/xpedition-cli 1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+> 中文版 → [CODE_OF_CONDUCT_zh.md](CODE_OF_CONDUCT_zh.md)
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
+
+## Our Pledge
+
+We pledge to make participation in `xpedition-cli` a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Respect differing viewpoints and experiences.
+- Accept constructive criticism with focus on the work.
+- Show empathy toward other community members.
+
+## Unacceptable Behavior
+
+- Harassment, intimidation, or discriminatory language.
+- Personal attacks, trolling, or insulting comments.
+- Publishing others' private information without explicit permission.
+- Other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this Code of Conduct. They may remove, edit, or reject comments, commits, issues, pull requests, or other contributions that do not align with it, and may temporarily or permanently ban any contributor for behavior they deem inappropriate.
+
+## Reporting
+
+Report unacceptable behavior privately to the project maintainers at **guosong6886@gmail.com**. All complaints will be reviewed and investigated promptly and fairly. Maintainers must respect the privacy and security of the reporter.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), version 2.1.

package/CODE_OF_CONDUCT_zh.md

@@ -0,0 +1,35 @@
+# 行为准则
+
+> English → [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+
+本项目遵循 [Contributor Covenant（贡献者公约）](https://www.contributor-covenant.org/zh-cn/) 2.1 版。
+
+## 我们的承诺
+
+我们承诺让每个人参与 `xpedition-cli` 的体验不受骚扰，无论其年龄、体型、是否残障、族裔、性别认同与表达、经验水平、国籍、个人外貌、种族、宗教信仰、性认同与性取向如何。
+
+## 期望的行为
+
+- 使用友善、包容的语言。
+- 尊重不同的观点和经验。
+- 以工作本身为重，接受建设性批评。
+- 对其他社区成员抱有同理心。
+
+## 不可接受的行为
+
+- 骚扰、恐吓或带有歧视性的言论。
+- 人身攻击、挑衅或侮辱性评论。
+- 未经明确许可公开他人的私人信息。
+- 其他在职业场景中会被合理认定为不当的行为。
+
+## 执行
+
+项目维护者负责阐释并执行本行为准则。维护者有权移除、编辑或拒绝任何不符合本准则的评论、提交、Issue、Pull Request 及其他贡献，并可对其认定为不当的行为暂时或永久封禁相关贡献者。
+
+## 举报
+
+如遇不可接受的行为，请私下向项目维护者举报：**guosong6886@gmail.com**。所有投诉都将被及时、公正地审查与处理。维护者必须尊重举报人的隐私与安全。
+
+## 出处
+
+本行为准则改编自 [Contributor Covenant（贡献者公约）](https://www.contributor-covenant.org/zh-cn/version/2/1/code_of_conduct/) 2.1 版。

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to xpedition-cli
+
+*English | [中文](CONTRIBUTING_zh.md)*
+
+Read [AGENTS.md](AGENTS.md) and the pinned `.agent/` specifications before
+changing behavior. The CLI is agent-first: stdout is a single JSON envelope,
+errors use the canonical code/exit/retryable mapping, and writes use
+`--dry-run` followed by a single-use `--confirm` token.
+
+## Development setup
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+ruff check xpedition_cli tests
+ruff format --check xpedition_cli tests
+node scripts/check-version.js
+node scripts/check-spec.js --local-only
+python -m xpedition_cli.main --help
+```
+
+Use `XPEDITION_CLI_CONFIG_DIR` for an isolated confirmation secret and audit
+directory during tests. Do not use production design files; native E2E is
+limited to the disposable sequence in [`docs/E2E.md`](docs/E2E.md).
+
+## Adding a command or backend
+
+1. Read the relevant sections of `.agent/CLI-SPEC.md` and `.agent/SEC-SPEC.md`.
+2. Add the domain model/backend operation under `xpedition_cli/`.
+3. Register the command, schema, examples, permission tier and blast radius in
+   `xpedition_cli/reference_data.py`.
+4. Keep external values marked in `_untrusted` and gate every mutating action
+   behind `--dry-run` then a single-use `--confirm <token>`, with `--dangerous`
+   as well when it destroys work.
+5. Add command-level tests for success, invalid input, errors, envelope shape,
+   exit code and stdout/stderr behavior. The FCC guard must remain green.
+6. Update both READMEs, the affected Skills and `CHANGELOG.md`.
+
+Do not claim NativeBackend or a new Xpedition version until a recorded licensed
+smoke test proves it. Keep `.agent/*`, `contract/contract.json`, and generated
+contract code synchronized through `scripts/sync-spec.js`; never hand-edit a
+vendored spec or generated module.
+
+## Pull requests
+
+- Use a focused branch and a Conventional Commit message.
+- Include tests and documentation for every observable behavior change.
+- Run lint, format, tests, version and spec guards locally.
+- Do not commit credentials, confidential design data, build artifacts or real tokens.
+

package/CONTRIBUTING_zh.md

@@ -0,0 +1,42 @@
+# 为 xpedition-cli 贡献代码
+
+*[English](CONTRIBUTING.md) | 中文*
+
+修改行为前先读 [AGENTS_zh.md](AGENTS_zh.md) 和固定版本的 `.agent/` 规范。本 CLI
+优先面向 Agent：stdout 只输出一个 JSON envelope，错误遵守统一的 code/exit/retryable
+映射，写操作使用 `--dry-run` 再配合单次 `--confirm` token。
+
+## 开发环境
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+ruff check xpedition_cli tests
+ruff format --check xpedition_cli tests
+node scripts/check-version.js
+node scripts/check-spec.js --local-only
+python -m xpedition_cli.main --help
+```
+
+测试时使用 `XPEDITION_CLI_CONFIG_DIR` 隔离确认 secret 和审计目录。不要使用生产工程文件；
+正版 E2E 只能执行 [`docs/E2E.md`](docs/E2E.md) 中的临时工程流程。
+
+## 新增命令或后端
+
+1. 先读 `.agent/CLI-SPEC.md` 和 `.agent/SEC-SPEC.md` 的相关章节。
+2. 在 `xpedition_cli/` 下增加领域模型或后端操作。
+3. 在 `xpedition_cli/reference_data.py` 注册命令、schema、examples、权限等级和爆炸半径。
+4. 外部值必须在 `_untrusted` 中标记；所有写操作都先 `--dry-run`，再用单次 `--confirm <token>` 执行，会毁掉成果的还要加 `--dangerous`。
+5. 为成功、非法输入、错误、envelope、退出码及 stdout/stderr 边界增加命令级测试，保持 FCC guard 通过。
+6. 同步修改两个 README、受影响的 Skill 和 `CHANGELOG.md`。
+
+没有经过授权环境的记录，不要宣称 NativeBackend 或新的 Xpedition 版本可用。`.agent/*`、
+`contract/contract.json` 和生成代码只能通过 `scripts/sync-spec.js` 保持同步，不要手改规范副本或生成文件。
+
+## Pull Request
+
+- 使用聚焦分支和 Conventional Commit。
+- 每个可观察行为变化都要有测试和文档。
+- 本地执行 lint、格式检查、测试、版本和 spec guard。
+- 不要提交凭据、机密工程数据、构建产物或真实 token。
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Guo <guosong6886@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,16 @@
+# Notice
+
+> 中文版 → [NOTICE_zh.md](NOTICE_zh.md)
+
+`xpedition-cli` is an independent open-source project. It is **not** affiliated with, endorsed by, sponsored by, or supported by Siemens or any of its affiliates.
+
+"Siemens Xpedition", related product and company names, logos, and brands are trademarks or registered trademarks of their respective owners. They are used here only to identify the API-compatibility target — that is, the software this tool talks to — and do not imply any association or endorsement.
+
+This project does not redistribute Siemens Xpedition code or assets. The
+NativeBackend works with Siemens Xpedition only inside the user's own licensed
+installation: through the product's automation interfaces and its own
+command-line tools, and on the project's files, as [SECURITY.md](SECURITY.md)
+describes. Nothing in this repository ships, wraps or replaces any part of the
+product itself.
+
+The MIT license (see [LICENSE](LICENSE)) applies only to the `xpedition-cli` source code. It grants no rights to Siemens Xpedition's trademarks, services, data, API behavior, or upstream availability.

package/NOTICE_zh.md

@@ -0,0 +1,13 @@
+# 声明
+
+> English → [NOTICE.md](NOTICE.md)
+
+`xpedition-cli` 是一个独立的开源项目，**与** Siemens 及其任何关联方**没有**从属、背书、赞助或支持关系。
+
+“Siemens Xpedition” 及相关产品名、公司名、徽标和品牌，均为各自所有者的商标或注册商标。此处提及仅用于标识 API 兼容目标——即本工具所对接的软件——并不表示存在任何关联或获得其认可。
+
+本项目不分发 Siemens Xpedition 的代码或资源。NativeBackend 只在用户自己的正版安装中工作：
+通过该产品的自动化接口和产品自带的命令行工具，以及直接处理工程文件，详见
+[SECURITY_zh.md](SECURITY_zh.md)。本仓库不包含、不封装、也不替代产品本身的任何部分。
+
+MIT 许可证（见 [LICENSE](LICENSE)）仅适用于 `xpedition-cli` 源代码，不授予 Siemens Xpedition 的商标、服务、数据、API 行为或上游可用性的任何权利。

package/README.md

@@ -0,0 +1,200 @@
+<h1 align="center">xpedition-cli</h1>
+
+<p align="center"><strong>Agent-native Xpedition design control with JSON-first reads and dry-run guarded ChangeSets</strong></p>
+
+<p align="center"><a href="README.md">English</a> · <a href="README_zh.md">中文</a></p>
+
+<p align="center">
+  <a href="https://github.com/fatecannotbealtered/xpedition-cli/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/fatecannotbealtered/xpedition-cli/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI"></a>
+  <a href="https://www.npmjs.com/package/@fateforge/xpedition-cli"><img alt="npm" src="https://img.shields.io/npm/v/@fateforge/xpedition-cli?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=CB3837"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7C3AED?style=for-the-badge"></a>
+</p>
+
+`xpedition-cli` is the command layer around Siemens Xpedition data. MockBackend
+works offline; NativeBackend drives a licensed Xpedition installation through an
+optional Windows COM adapter, and has taken a project from an empty schematic to a
+routed board and a fabrication package (`docs/E2E.md`). That evidence comes from one
+Windows installation, with converted open-source footprints and placeholder part
+numbers. The CLI never edits Xpedition's private databases directly, and every
+write command is gated by `--dry-run` then `--confirm <token>`.
+
+## Agent Install
+
+```bash
+python -m pip install "xpedition-cli[native] @ git+https://github.com/fatecannotbealtered/xpedition-cli"
+npx skills add fatecannotbealtered/xpedition-cli -y -g
+
+xpedition-cli context --compact
+xpedition-cli doctor --compact
+xpedition-cli reference --compact
+```
+
+The first line installs the CLI and its Windows adapter (`[native]`) from this
+repository's default branch; append a release tag to pin one, e.g.
+`...xpedition-cli@v1.0.0`. From a checkout, `python -m pip install -e ".[native]"`
+does the same. Each tagged release also publishes a standalone binary to npm as
+`@fateforge/xpedition-cli`. It has no Windows adapter, so it serves MockBackend,
+offline planning and file commands only; driving Xpedition needs the pip install
+on Windows. No CLI login is required for MockBackend. Native Xpedition
+credentials and licensing remain inside the verified Xpedition environment; see
+[Native adapter protocol](docs/NATIVE_ADAPTER.md).
+
+## What It Does
+
+The CLI normalizes project snapshots, BOM rows, connectivity and deterministic
+review findings. A ChangeSet describes controlled operations such as placing a
+component, creating a net, connecting pins, moving or deleting a component, and
+setting a property. Applying a ChangeSet requires a preview token, writes a
+backup when replacing an existing file, saves atomically, and verifies the project after the write.
+
+Risk tier: **T2**. Against MockBackend the blast radius is the explicitly named
+local JSON file. Against NativeBackend it is the named Xpedition project: a
+confirmed write can draw a schematic, place parts, and add or delete routing.
+The writes that destroy work also need `--dangerous` next to the token:
+`schematic draw`, `pcb unroute`, `pcb create --replace` (which first archives the
+layout folder to a zip beside the project), `pcb arrange` on a routed board,
+`pcb route --unroute`, `pcb annotate --unroute`, and `library kicad-import` into a
+partition that exists. `pcb annotate`, `pcb export` when it changes the output
+setups, and the first `pcb show --top-view` on a board close and reopen the board
+without saving it, so save hand edits in Layout first. See [SECURITY.md](SECURITY.md).
+
+## Capabilities
+
+| Area | Commands | Backend |
+|---|---|---|
+| Project data | `project init`, `project info`, `project tree`, `project snapshot`, `project diff`, `design snapshot` | both; natively `project init --template` copies a template project, and `project diff` compares a MockBackend file with its backup |
+| Schematic reads | `schematic sheets`, `components`, `pins`, `nets`, `connectivity`, `unconnected`, `power`, `interfaces`, `query` | both |
+| Schematic drawing | `schematic draw`, `schematic show`, `schematic export`, `library build`, `library kicad-import` | NativeBackend (see below) |
+| Pin planning | `schematic pin-plan`, `schematic pin-check` | offline, against a supplied snapshot |
+| PCB reads | `pcb info`, `components`, `footprints`, `nets`, `tracks`, `vias`, `layers`, `stackup`, `zones`, `keepouts`, `query` | both; natively only components, footprints, nets, tracks and vias are read, and the rest come back empty |
+| PCB design | `pcb create`, `annotate`, `outline`, `holes`, `arrange`, `placement`, `move`, `rules`, `pour`, `route`, `trace`, `via`, `unroute`, `labels`, `geometry`, `render`, `show`, `drc`, `export` | NativeBackend (see below) |
+| PCB planning | `pcb stitch`, `pcb placement-plan` | offline, from files |
+| Constraints/analysis | `constraints ...`, `analysis run|results|erc|drc|dfm` | MockBackend; natively `analysis run` is refused and the reads come back empty (use `review run` and `pcb drc`) |
+| Manufacturing/library reads | `manufacturing ...`, `library search|parts|symbols|footprints|padstacks|models|validate` | MockBackend; natively they come back empty |
+| Change control | `change validate`, `change preview`, `change apply`, `change history`, `change rollback`, `schematic apply` | MockBackend; natively `change apply` places and moves parts, and `schematic apply` also creates nets and connects pins |
+| Review and BOM | `review run`, `bom export|normalize|group|variants|missing|duplicates|validate|compare` | both; natively `review run` adds Designer's own verification |
+| Environment | `context`, `doctor`, `reference`, `changelog`, `system capabilities`, `system license`, `system api-inventory` | local probe; `api-inventory` reads COM type libraries on Windows |
+| Knowledge base | `kb list`, `kb add`, `kb remove` | local links to company rules; the agent reads them |
+| Session | `session status`, `session logs`, `session start`, `session attach`, `session open`, `session stop` | start/attach/open/stop drive Xpedition; `session logs` reads a log this version never writes |
+| Exchange files | `exchange inspect`, `exchange import` | JSON/CSV/BOM/IPC-2581; PDF/EDN/ODB++ remain unavailable |
+| Agent bridge | `agent snapshot`, `agent query`, `agent review`, `agent capabilities`, `agent serve` | MockBackend unless the native backend is selected; `serve` supports custom NDJSON and MCP transports |
+| Planned | native constraints, analysis, manufacturing and library reads; PDF/EDN/ODB++ imports; the rest of the native ChangeSet operations | listed in `system capabilities` |
+
+The live command and schema source is `xpedition-cli reference --compact`.
+
+## Agent Workflow
+
+1. Run `context`, `doctor`, and `reference`; check the backend and release readiness.
+2. Keep `--backend mock` and `--project PATH` explicit for offline work.
+3. Use `--compact` and `--fields` when passing JSON between agent steps.
+4. To create a new MockBackend project, run `project init --dry-run`, inspect
+   the preview, then confirm with the same arguments.
+5. Validate and preview a ChangeSet before applying it:
+
+   ```bash
+   xpedition-cli change validate --changeset ./changeset.json --compact
+   xpedition-cli change apply --backend mock --project ./demo-project.json --changeset ./changeset.json --dry-run --compact
+   xpedition-cli change apply --backend mock --project ./demo-project.json --changeset ./changeset.json --confirm <confirm_token> --backup --compact
+   ```
+
+6. After applying, inspect `verification`; re-read `project snapshot` before any next write.
+7. Use `change history` to inspect local operations. Rollback also requires a
+   dry-run preview and a one-time confirmation token.
+
+Agent integrations can use `xpedition-cli agent serve --transport stdio` for a
+newline-delimited JSON request/response stream. It exposes snapshot, query,
+review and capability methods, on MockBackend unless a request selects the
+native backend.
+
+## Native Xpedition: from the schematic to the fabrication package
+
+The stages below have run on a licensed Xpedition (XPED2604) against the example
+project -- apart from `pcb via` on its own and the guarded `library kicad-import`,
+whose converter ran through an earlier entry point. The runs are recorded in
+[docs/E2E.md](docs/E2E.md) and every fact learnt
+about the automation in [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md). Write
+commands are guarded: `--dry-run` returns a `confirm_token`, `--confirm <token>` acts.
+
+| Stage | Commands |
+|---|---|
+| Project and schematic | `project init`, `schematic draw`, `schematic show`, `schematic export`, `review run` |
+| Library | `library build` (parts from a design file), `library kicad-import` (cells from KiCad footprint libraries) |
+| Board | `pcb create`, `pcb annotate`, `pcb outline`, `pcb holes`, `pcb arrange`, `pcb placement`, `pcb pour`, `pcb rules`, `pcb route`, `pcb drc` |
+| By hand | `pcb geometry`, `pcb trace`, `pcb via`, `pcb unroute`, `pcb move`, `pcb labels`, `pcb stitch` (plans offline; the plan checks are in `xpedition_cli.routing_plan`) |
+| Pictures and output | `pcb render`, `pcb show [--top-view]`, `pcb export` (ODB++, Gerber, NC drill, centroid, BOM, manifest) |
+
+## Machine Contract
+
+- JSON is the default and stdout contains exactly one envelope.
+- Success and failure both include `ok`, `schema_version`, and `meta.duration_ms`.
+- Errors use the canonical `E_*` to exit-code and `retryable` mapping in
+  [`contract/contract.json`](contract/contract.json).
+- Logs and diagnostics go to stderr. `--json` is a compatibility alias for
+  `--format json`; `--format text` is for humans and `raw` returns the payload.
+- Project and review values that can originate in files are marked in `_untrusted`.
+- IDs are strings and timestamps are ISO 8601 UTC.
+
+## Configuration
+
+The CLI has no login flow in this phase. It keeps its local state under
+`~/.xpedition-cli/`: the confirmation secret, the consumed-token ledger and its
+lock, the audit JSONL, knowledge-base links, the native session record
+(`session.json`) and placement locks. Set `XPEDITION_CLI_CONFIG_DIR` to isolate these files in
+tests or CI. Set `XPEDITION_NATIVE_COMMAND` to select an adapter when needed;
+setting it does not bypass COM registration or license checks.
+
+Company rules -- layout rules, drawing conventions, review checklists -- stay in
+the company's knowledge base. `kb add --name NAME --url URL --about TEXT` (a
+write: dry run, then confirm) records which document applies, in
+`knowledge-base.json`, and `context` lists them for the agent, which reads each
+with its own tools (for a Feishu wiki, lark-cli). The CLI never fetches a
+document.
+
+## Project Structure
+
+```text
+xpedition-cli/
+├── xpedition_cli/       # CLI boundary, models, ChangeSet, backends, contract
+├── tests/               # command-level contract and FCC tests
+├── skills/xpedition-cli/        # entry Skill: install, sessions, projects, ChangeSets
+├── skills/xpedition-schematic/  # schematic Skill: Designer drawing, review, pins
+├── skills/xpedition-pcb/        # board Skill: Layout, routing, DRC, fabrication
+├── contract/            # canonical vendored machine contract
+├── scripts/             # spec, version, and npm wrapper tooling
+├── docs/                # compatibility, E2E, and open-source checklist
+└── .agent/              # pinned AI-native CLI specifications
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+ruff check xpedition_cli tests
+ruff format --check xpedition_cli tests
+node scripts/check-version.js
+node scripts/check-spec.js --local-only
+```
+
+`reference.release_readiness.level` is `beta`: every public command has a
+command-level test and the contract tests cover the failure and boundary behaviour
+as well as the happy path, and live runs against a licensed Xpedition are recorded
+in [`docs/E2E.md`](docs/E2E.md); `reference` names what still keeps it from
+`stable`. The level is a statement about that evidence, not a promise that the
+Xpedition automation behaves identically on another installation.
+
+## Links
+
+- [Agent entry](AGENTS.md)
+- [Skills](skills/xpedition-cli/SKILL.md): the entry Skill, with [xpedition-schematic](skills/xpedition-schematic/SKILL.md) and [xpedition-pcb](skills/xpedition-pcb/SKILL.md)
+- [CLI contract](.agent/CLI-SPEC.md)
+- [Security policy](SECURITY.md)
+- [Compatibility matrix](docs/COMPATIBILITY.md)
+- [Native adapter protocol](docs/NATIVE_ADAPTER.md)
+- [MCP transport](docs/MCP.md)
+- [E2E notes](docs/E2E.md)
+- [Skill evaluations across models](docs/EVALS.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Third-party notice](NOTICE.md)
+- [MIT license](LICENSE)

package/README_zh.md

@@ -0,0 +1,178 @@
+<h1 align="center">xpedition-cli</h1>
+
+<p align="center"><strong>面向 AI Agent 的 Xpedition 设计控制层：JSON 优先，ChangeSet 写入受 dry-run 保护</strong></p>
+
+<p align="center"><a href="README.md">English</a> · <a href="README_zh.md">中文</a></p>
+
+<p align="center">
+  <a href="https://github.com/fatecannotbealtered/xpedition-cli/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/fatecannotbealtered/xpedition-cli/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI"></a>
+  <a href="https://www.npmjs.com/package/@fateforge/xpedition-cli"><img alt="npm" src="https://img.shields.io/npm/v/@fateforge/xpedition-cli?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=CB3837"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7C3AED?style=for-the-badge"></a>
+</p>
+
+`xpedition-cli` 是 Siemens Xpedition 数据的命令层。MockBackend 可离线使用；
+NativeBackend 通过可选的 Windows COM 适配器驱动正版 Xpedition，已经把一个工程从空白原理图
+一路做到布线完成的板子和整套打板资料（见 `docs/E2E.md`）。这些证据来自同一台 Windows 机器，
+封装是转换来的开源库，料号是占位值。CLI 不直接修改 Xpedition 私有数据库，
+所有写命令都要先 `--dry-run` 再 `--confirm <token>`。
+
+## Agent 安装
+
+```bash
+python -m pip install "xpedition-cli[native] @ git+https://github.com/fatecannotbealtered/xpedition-cli"
+npx skills add fatecannotbealtered/xpedition-cli -y -g
+
+xpedition-cli context --compact
+xpedition-cli doctor --compact
+xpedition-cli reference --compact
+```
+
+第一行从本仓库的默认分支安装 CLI 和 Windows 适配器（`[native]`）；要固定到某个发布版本，
+在末尾加上 tag，例如 `...xpedition-cli@v1.0.0`。在代码检出目录中用
+`python -m pip install -e ".[native]"` 效果相同。每次打 tag 发版还会把独立二进制发布到 npm，
+包名 `@fateforge/xpedition-cli`。它不带 Windows 适配器，只能用于 MockBackend、离线规划和
+文件类命令；要驱动 Xpedition，必须在 Windows 上用 pip 安装。MockBackend 不需要 CLI 登录；Native
+Xpedition 的凭据和许可证留在经过验证的 Xpedition 环境内，详见
+[NativeBackend 适配器协议](docs/NATIVE_ADAPTER.md)。
+
+## 它做什么
+
+CLI 负责标准化工程快照、BOM、连通性和确定性的审查结果。ChangeSet 描述放置器件、
+创建网络、连接引脚、移动或删除器件、设置属性等受控操作。应用 ChangeSet 必须先拿到
+预览 token，替换已有文件时自动生成备份，随后原子保存并回读验证。
+
+风险等级：**T2**。对 MockBackend，爆炸半径是明确指定的那个本地 JSON 文件。对 NativeBackend，
+爆炸半径是指定的那个 Xpedition 工程：一次确认过的写入可以画原理图、摆器件、增删布线。
+会毁掉成果的写操作，除了 token 还要加 `--dangerous`：`schematic draw`、`pcb unroute`、
+`pcb create --replace`（会先把已有布局目录打包成工程旁边的 zip，再删除它）、有布线时的
+`pcb arrange`、`pcb route --unroute`、`pcb annotate --unroute`，以及导入到已存在分区的
+`library kicad-import`。`pcb annotate`、改动了输出设置的 `pcb export`，以及对一块板第一次
+运行的 `pcb show --top-view`，都会不存盘地关闭并重新打开板子，所以先在 Layout 里保存手工改动。
+参见 [SECURITY_zh.md](SECURITY_zh.md)。
+
+## 能力
+
+| 领域 | 命令 | 后端 |
+|---|---|---|
+| 工程数据 | `project init`、`project info`、`project tree`、`project snapshot`、`project diff`、`design snapshot` | 两种后端；原生下 `project init --template` 复制模板工程，`project diff` 比对的是 MockBackend 文件和它的备份 |
+| 原理图读取 | `schematic sheets`、`components`、`pins`、`nets`、`connectivity`、`unconnected`、`power`、`interfaces`、`query` | 两种后端 |
+| 原理图绘制 | `schematic draw`、`schematic show`、`schematic export`、`library build`、`library kicad-import` | NativeBackend（见下节） |
+| 引脚规划 | `schematic pin-plan`、`schematic pin-check` | 离线，基于提供的快照 |
+| PCB 读取 | `pcb info`、`components`、`footprints`、`nets`、`tracks`、`vias`、`layers`、`stackup`、`zones`、`keepouts`、`query` | 两种后端；原生下只读元件、封装、网络、走线和过孔，其余返回空 |
+| PCB 设计 | `pcb create`、`annotate`、`outline`、`holes`、`arrange`、`placement`、`move`、`rules`、`pour`、`route`、`trace`、`via`、`unroute`、`labels`、`geometry`、`render`、`show`、`drc`、`export` | NativeBackend（见下节） |
+| PCB 规划 | `pcb stitch`、`pcb placement-plan` | 离线，基于文件 |
+| 约束与分析 | `constraints ...`、`analysis run|results|erc|drc|dfm` | MockBackend；原生下 `analysis run` 会被拒绝，读取命令返回空（请用 `review run` 和 `pcb drc`） |
+| 制造与库读取 | `manufacturing ...`、`library search|parts|symbols|footprints|padstacks|models|validate` | MockBackend；原生下返回空 |
+| 变更控制 | `change validate`、`change preview`、`change apply`、`change history`、`change rollback`、`schematic apply` | MockBackend；原生下 `change apply` 能放置和移动器件，`schematic apply` 还能建网络、连引脚 |
+| 审查与 BOM | `review run`、`bom export|normalize|group|variants|missing|duplicates|validate|compare` | 两种后端；原生下 `review run` 还会跑 Designer 自带的校验 |
+| 环境 | `context`、`doctor`、`reference`、`changelog`、`system capabilities`、`system license`、`system api-inventory` | 本地探针；`api-inventory` 在 Windows 上读取 COM 类型库 |
+| 知识库 | `kb list`、`kb add`、`kb remove` | 本地记录公司规则文档的链接，由 Agent 去读 |
+| 会话 | `session status`、`session logs`、`session start`、`session attach`、`session open`、`session stop` | start/attach/open/stop 驱动 Xpedition；`session logs` 读取的日志本版本从不写入 |
+| Exchange 文件 | `exchange inspect`、`exchange import` | JSON/CSV/BOM/IPC-2581；PDF/EDN/ODB++ 仍不可用 |
+| Agent 桥接 | `agent snapshot`、`agent query`、`agent review`、`agent capabilities`、`agent serve` | 默认 MockBackend，选了原生后端时走原生；`serve` 支持自定义 NDJSON 和 MCP transport |
+| 规划中 | 约束、分析、制造和库读取的原生实现；PDF/EDN/ODB++ 导入；其余原生 ChangeSet 操作 | 列在 `system capabilities` 里 |
+
+实时命令和 schema 以 `xpedition-cli reference --compact` 为准。
+
+## Agent 工作流
+
+1. 运行 `context`、`doctor`、`reference`，确认后端和发布就绪等级。
+2. 离线工作时显式使用 `--backend mock` 和 `--project PATH`。
+3. 在 Agent 步骤之间传递 JSON 时使用 `--compact` 和 `--fields`。
+4. 创建新的 MockBackend 工程时先运行 `project init --dry-run`，检查预览后使用相同参数确认。
+5. 应用 ChangeSet 前先校验和预览：
+
+   ```bash
+   xpedition-cli change validate --changeset ./changeset.json --compact
+   xpedition-cli change apply --backend mock --project ./demo-project.json --changeset ./changeset.json --dry-run --compact
+   xpedition-cli change apply --backend mock --project ./demo-project.json --changeset ./changeset.json --confirm <confirm_token> --backup --compact
+   ```
+
+6. 应用后检查 `verification`，并在下一次写入前重新读取 `project snapshot`。
+7. 使用 `change history` 查看本地操作记录。回滚同样必须先预览，再使用一次性确认 token。
+
+Agent 集成可使用 `xpedition-cli agent serve --transport stdio`，通过 NDJSON
+请求/响应流访问 snapshot、query、review 和 capability 方法；除非请求选了原生后端，否则走 MockBackend。
+
+## 原生 Xpedition：从原理图到打板资料
+
+下面各阶段都在有许可的 Xpedition（XPED2604）上对示例工程跑通过；例外是单独运行的
+`pcb via`，以及带门禁的 `library kicad-import`（它背后的转换器是通过早先的入口跑的）。过程记录在
+[docs/E2E.md](docs/E2E.md)，自动化接口的每条事实在 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。
+写命令都有门禁：`--dry-run` 返回 `confirm_token`，`--confirm <token>` 才执行。
+
+| 阶段 | 命令 |
+|---|---|
+| 工程与原理图 | `project init`、`schematic draw`、`schematic show`、`schematic export`、`review run` |
+| 库 | `library build`（零件来自设计文件）、`library kicad-import`（封装由 KiCad 封装库转换） |
+| 板子 | `pcb create`、`pcb annotate`、`pcb outline`、`pcb holes`、`pcb arrange`、`pcb placement`、`pcb pour`、`pcb rules`、`pcb route`、`pcb drc` |
+| 手工布线 | `pcb geometry`、`pcb trace`、`pcb via`、`pcb unroute`、`pcb move`、`pcb labels`、`pcb stitch`（离线规划；计划检查在 `xpedition_cli.routing_plan`） |
+| 出图与出资料 | `pcb render`、`pcb show [--top-view]`、`pcb export`（ODB++、Gerber、钻孔、坐标、BOM、清单） |
+
+## 机器契约
+
+- 默认输出 JSON，stdout 只包含一个 envelope。
+- 成功和失败都包含 `ok`、`schema_version` 和 `meta.duration_ms`。
+- 错误使用 [`contract/contract.json`](contract/contract.json) 中统一的 `E_*`、退出码和 `retryable` 映射。
+- 日志和诊断走 stderr；`--json` 是 `--format json` 的兼容别名，`text` 面向人，`raw` 返回 payload。
+- 来自工程文件的项目和审查字段通过 `_untrusted` 标记。
+- ID 使用字符串，时间使用 ISO 8601 UTC。
+
+## 配置
+
+本阶段没有登录流程。CLI 的本地状态都在 `~/.xpedition-cli/` 下：确认 secret、已消费 token
+记录及其锁文件、审计 JSONL、知识库链接、原生会话记录（`session.json`）和摆放任务的锁文件。
+测试或 CI 可设置 `XPEDITION_CLI_CONFIG_DIR` 隔离这些文件。Native
+适配器可通过 `XPEDITION_NATIVE_COMMAND` 指定；设置该变量不会绕过 COM 注册或许可证检查。
+
+公司自己的规则（布局规则、绘图约定、评审清单）留在公司知识库里。
+`kb add --name NAME --url URL --about TEXT`（写操作：先 dry-run 再 confirm）把适用的文档记到
+`knowledge-base.json`，`context` 把它们列给 Agent，由 Agent 用自己的工具去读（飞书 wiki 用
+lark-cli）。CLI 本身从不读取文档。
+
+## 项目结构
+
+```text
+xpedition-cli/
+├── xpedition_cli/       # CLI 边界、模型、ChangeSet、后端、契约
+├── tests/               # 命令级契约和 FCC 测试
+├── skills/xpedition-cli/        # 入口 Skill：安装、会话、工程、ChangeSet
+├── skills/xpedition-schematic/  # 原理图 Skill：Designer 绘图、评审、引脚
+├── skills/xpedition-pcb/        # 板级 Skill：Layout、布线、DRC、制造输出
+├── contract/            # vendored 机器契约真源
+├── scripts/             # 规范、版本和 npm 壳工具
+├── docs/                # 兼容性、E2E 和开源清单
+└── .agent/              # 固定版本的 AI 原生 CLI 规范
+```
+
+## 开发
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+ruff check xpedition_cli tests
+ruff format --check xpedition_cli tests
+node scripts/check-version.js
+node scripts/check-spec.js --local-only
+```
+
+当前 `reference.release_readiness.level` 为 `beta`：每条公开命令都有命令级测试，
+契约测试覆盖失败路径和边界行为而不只是正常路径，正版 Xpedition 上的真实运行记录在
+[`docs/E2E.md`](docs/E2E.md)；离 `stable` 还差什么，`reference` 里写着。这个等级说的是
+这些证据，不等于承诺换一台机器上的 Xpedition 自动化行为完全一致。
+
+## 链接
+
+- [Agent 入口](AGENTS_zh.md)
+- [Skill](skills/xpedition-cli/SKILL.md)（入口），以及 [xpedition-schematic](skills/xpedition-schematic/SKILL.md) 和 [xpedition-pcb](skills/xpedition-pcb/SKILL.md)
+- [CLI 契约](.agent/CLI-SPEC.md)
+- [安全策略](SECURITY_zh.md)
+- [兼容性矩阵](docs/COMPATIBILITY.md)
+- [NativeBackend 适配器协议](docs/NATIVE_ADAPTER.md)
+- [MCP transport](docs/MCP.md)
+- [E2E 说明](docs/E2E.md)
+- [Skill 跨模型评测](docs/EVALS.md)
+- [变更记录](CHANGELOG.md)
+- [贡献说明](CONTRIBUTING_zh.md)
+- [第三方声明](NOTICE_zh.md)
+- [MIT 许可证](LICENSE)