# 贡献指南与文档规范 如何为 StampDEX 技术文档提交 PR、运行质量检查套件与参与双语翻译。 > Source: bitcoinuniverseio/docs-stampdex, this repository. Applicable release continuous deployment, verify with GET /api/version. Last verified 2026-09-01. Chain bitcoin/mainnet. > [!NOTE] > **简体中文官方文档**：包含代码风格、无破折号约束、术语表规范与自动化流水线运行说明。 核心交易规则为非托管模式，买卖双方按标准费率收取服务费，并于比特币主网进行原子结算。 Corrections and improvements are welcome. A wrong sentence about where somebody's money is costs more than a missing one, so corrections are the most valuable contribution here. ## How - **Found a mistake or a gap:** open an [issue](https://github.com/bitcoinuniverseio/docs-stampdex/zh-cn/issues) naming the page and the problem. - **Have the fix:** open a pull request. Every page carries an Edit on GitHub link under its title that takes you straight to the file. ## Running the site locally ```bash frame=none npm install npm run dev npm run build npm test ``` `npm test` runs the runner policy check, the copy checks, and the manifest validation. `npm run build` validates every internal link and builds the search index. ## Writing rules - Short, plain sentences. One idea per sentence. - State facts you can verify against the live product, the public API, or the ecosystem capability registry. If you cannot verify a claim, do not write it. - **Never use a long dash.** The build fails on one. - Say authoritative, owning, official, or the source of truth. One near synonym for those is banned in prose and the copy guard rejects it. - No marketing vocabulary. `scripts/check-docs.mjs` holds the rejected list, and the build fails on any of them. - Test every command before committing it, and say what to expect back. - A missing value is unknown, not zero. The docs follow the same honesty rule the product does. - Prefer a diagram or a table over a paragraph. Diagrams are inline SVG with a title and a description, and they must read in both themes. ## The colour rule Four colours carry meaning on this site, and nothing else is coloured: | Colour | Meaning | | --- | --- | | Buyer teal | Held by the buyer, or delivered to the buyer | | Seller amber | Held by the seller, or delivered to the seller | | Venue violet | Held by StampDEX for the length of one trade | | Chain green | Settled on Bitcoin, final | If you add a diagram, use those and no others. A reader who has learned the legend on one page should not have to relearn it on the next. ## The grounding rule Code presence is not released capability. A route existing is not production availability. A parser existing is not wallet support. When the ecosystem capability registry records an action as unsupported, use the registry's own recorded reason. It is usually the most useful sentence on the page. See [What you can and cannot do](/docs-stampdex/zh-cn/capabilities/). ## What does not belong here - Credentials, keys, internal host names, private ports, or operator procedure. Private material lives in the private repositories. - Documentation for features that are not live. Describe what works today, and use [Release evidence](/docs-stampdex/zh-cn/project/release-evidence/) to say what has and has not been verified. - Fabricated screenshots. If no real capture exists, draw a diagram and describe the interface in words. ## Related - [Page freshness](/docs-stampdex/zh-cn/project/page-freshness/) - [Changelog](/docs-stampdex/zh-cn/project/changelog/) ## Screenshot evidence Product screenshots are not hand-dropped into assets. They are declared in screenshots.manifest.json, captured by a runner, and held to that declaration by a gate. To add or refresh a capture: 1. Add or edit its record in scripts/gen-screens-manifest.mjs and run `npm run gen:screens-manifest`. A production capture records the application commit it expects; the runner refuses to capture anything else. 2. Run `npm run capture:screens`. Production mode opens the public, read-only screen, waits for its heading, masks the volatile regions the manifest declares, and saves the master. Fixture mode records a deterministic page from scripts/fixtures and is always visibly labelled as a controlled recorded state. 3. Run `npm run make:responsive-screens` to generate the served variants. 4. Run `npm run check:screens`. It fails on missing masters or variants, images over the size budget, captures past their freshness window, undeclared files, and anything the secret scan dislikes. Reference a capture in a page with the screenshot components, which read the same manifest: ``. The [Visual product atlas](/docs-stampdex/product-atlas/) lists every capture with its evidence. The documentation's own look is guarded by visual baselines. A screenshot that changed is a review event, never an automatic approval: refresh baselines only with `npm run visual:update` and commit the difference.