server-handbook 0.1.0__tar.gz

server_handbook-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.whl binary
+*.gz binary

server_handbook-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Changes are proposals until the repository owner reviews and merges them.
+* @zzy1136660162

server_handbook-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug report / 问题反馈
+description: Report a reproducible problem with Server Handbook.
+title: "[Bug]: "
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Version / 版本
+      description: Output of server-handbook --version.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment / 运行环境
+      description: OS, Python, Docker/Compose or systemd versions, and CLI or MCP usage.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction / 复现步骤
+      description: Use a small anonymous example. Include the command, expected behavior and actual result.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Relevant output / 相关结果
+      description: Include the smallest useful error or check result. Remove passwords, tokens and private server data.

server_handbook-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

server_handbook-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request / 功能建议
+description: Explain a server-maintenance task this project could support.
+title: "[Feature]: "
+body:
+  - type: textarea
+    id: task
+    attributes:
+      label: User task / 使用场景
+      description: What are you trying to accomplish, and what currently gets in the way?
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Expected outcome / 期望结果
+      description: Describe the observable behavior that would solve the task.
+    validations:
+      required: true

server_handbook-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Problem and resulting behavior
+
+Describe the user task and what changes after this PR.
+
+## Validation
+
+List the checks actually performed, and distinguish simulated service tests from real execution.
+
+## Limits
+
+State any unverified behavior or migration requirements. Pull requests are proposals; only the maintainer decides what is merged into the original repository.

server_handbook-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: checks
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-and-package:
+    strategy:
+      matrix:
+        os: [ubuntu-24.04, windows-latest]
+        python: ["3.11", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.1.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[mcp,dev]"
+      - run: python -m pytest -q
+      - run: python -m build
+
+  real-compose:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.1.0
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -e ".[mcp,dev]"
+      - run: docker pull nginx:alpine
+      - run: python -m pytest -q -s tests/test_docker_integration.py
+        env:
+          SERVER_HANDBOOK_DOCKER_TESTS: "1"
+
+  ci-success:
+    if: always()
+    needs: [unit-and-package, real-compose]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Require all validation jobs
+        env:
+          UNIT_RESULT: ${{ needs['unit-and-package'].result }}
+          COMPOSE_RESULT: ${{ needs['real-compose'].result }}
+        run: |
+          test "$UNIT_RESULT" = success
+          test "$COMPOSE_RESULT" = success

server_handbook-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,78 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Exact version already committed in server_handbook.__version__
+        required: true
+        type: string
+        default: "0.1.0"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.repository == 'zzy1136660162/server-handbook' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7.1.0
+        with:
+          python-version: "3.13"
+      - name: Install build and test tools
+        run: python -m pip install -e ".[mcp,dev]" twine
+      - name: Check the requested version
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          from server_handbook import __version__
+          requested = os.environ["RELEASE_VERSION"]
+          if requested != __version__:
+              raise SystemExit("Requested version does not match the committed package version.")
+          print("Building Server Handbook", __version__)
+          PY
+      - name: Run package tests
+        run: python -m pytest -q
+      - name: Build and validate distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+      - name: Verify installed wheel and stdio MCP
+        run: |
+          python -m pip install --force-reinstall --no-deps dist/*.whl
+          python tools/verify_installed.py --output verification/pypi-wheel-check.json
+      - uses: actions/upload-artifact@v7.0.2
+        with:
+          name: pypi-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    needs: build
+    if: github.repository == 'zzy1136660162/server-handbook' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/project/server-handbook/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.2
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish through PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@v1.14.3

server_handbook-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv*/
+build/
+dist/
+*.egg-info/
+.server-handbook/
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+verification/
+.env
+.env.*
+!.env.example

server_handbook-0.1.0/AGENTS.md

@@ -0,0 +1,9 @@
+# Server Handbook development
+
+Users are self-hosted Linux server owners and their authorized coding agents. The core tasks are zero-context handoff, adopting existing directories, and recording managed deployments. Success means real checks and durable records agree, existing data/manual documentation remain intact, and unfinished work is visible.
+
+This is an independent local open-source project. Do not connect to or modify the existing family server, copy private files, or import its real inventory. Use anonymous temporary fixtures. No package/repository publication without explicit instructions.
+
+Use Python standard library for the CLI and local SQLite state; MCP is an optional extra. All entry points share validation and persistence. Declarations, live observations, and operation receipts are distinct. Never execute descriptor `commands` strings. Failures and interruptions must not become success. Preserve user-authored README/AGENTS content outside clearly managed blocks. No shell=True, automatic data deletion, generic shell MCP tools, or global root daemon.
+
+Run meaningful tests, build wheel/sdist, inspect package contents, install a wheel into an isolated environment, and test real stdio MCP. Report simulated service tests separately from real Linux/Docker checks.

server_handbook-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Issues and pull requests are welcome. Public visitors have read access and can propose changes from a fork; they cannot push to this repository or merge their own proposals. The repository owner reviews and decides what enters `main`. Write access is granted only through an explicit maintainer invitation. The MIT license also permits modifying and distributing a separate copy; repository access controls protect this original repository.
+
+欢迎提交 Issue 或通过 Fork 提交 PR。普通访客不能直接推送、合并或修改本仓库；是否采纳由维护者决定。MIT 开源允许修改自己的副本，并不意味着取得原仓库写入权限。
+
+Use Python 3.11 or newer. Create an isolated environment, install `.[mcp,dev]`, run `python -m pytest` and `python -m build`. CLI logic belongs in the shared core; MCP and CLI must not develop different registration or execution rules.
+
+Start changes with the user task and the observable result. Use temporary workspaces and anonymous fixtures. Do not copy a real server's credentials, inventory, application data, user documents, or operation transcripts into the repository.
+
+Keep declarations, observations and receipts distinct. Add meaningful tests for failed writes, stale revisions, interruptions and pre-existing manual content when those behaviors change. Unknown database versions require an explicit migration design; never silently recreate state.
+
+Default tests must not affect the developer's Docker or system services. The explicit optional Docker test uses its own unique project with no persistent mounts and must clean up only that project. Report real and simulated execution separately.
+
+Generated documentation must preserve user-authored content outside managed markers. Do not add arbitrary shell MCP tools, automatic data resets, secret-returning document tools or generic root daemons as shortcuts.
+
+Before a release, inspect both wheel and sdist, install the wheel in a fresh environment, exercise stdio MCP, and verify bundled schema/Skill assets. Public publishing is a maintainer action with the chosen account and package name; local build does not publish anything.

server_handbook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Server Handbook contributors
+
+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.

server_handbook-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE README.md README.zh-CN.md CONTRIBUTING.md SECURITY.md AGENTS.md .gitignore .gitattributes
+recursive-include .github *.yml *.md CODEOWNERS
+recursive-include docs *.md *.xml
+recursive-include examples *.md *.json *.yaml
+recursive-include tests *.py
+recursive-include tools *.py
+recursive-include src/server_handbook/assets *

server_handbook-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: server-handbook
+Version: 0.1.0
+Summary: Durable server context, deployment registry, and tracked operations for humans and AI agents
+Author: Server Handbook contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zzy1136660162/server-handbook
+Project-URL: Repository, https://github.com/zzy1136660162/server-handbook
+Project-URL: Issues, https://github.com/zzy1136660162/server-handbook/issues
+Project-URL: Documentation, https://github.com/zzy1136660162/server-handbook/blob/main/README.zh-CN.md
+Keywords: mcp,devops,self-hosted,deployment,agents,handoff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp==2.3.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: jsonschema>=4.20; extra == "dev"
+Dynamic: license-file
+
+# Server Handbook
+
+Server context, deployment registration, and tracked operations for humans and AI agents.
+
+[中文说明](README.zh-CN.md) · [Architecture](docs/architecture.md) · [CLI reference](docs/cli.md) · [MCP setup](docs/mcp.md)
+
+[Source](https://github.com/zzy1136660162/server-handbook) · [Report an issue](https://github.com/zzy1136660162/server-handbook/issues) · [PyPI publishing guide](docs/pypi-publishing.zh-CN.md)
+
+Server Handbook gives a new agent a predictable place to start, records where services live, and saves actual results from managed Compose/systemd actions. Existing projects can stay in their current directories. Manual README and AGENTS content outside marked blocks is preserved.
+
+**Status:** 0.1.0 alpha. The source and local distributions are usable; this project has not been published to PyPI. Core commands use only the Python standard library. MCP is an optional extra. Service execution targets Linux/Compose; clients and registry operations are portable.
+
+## Install from this checkout
+
+Python 3.11 or newer is required. Use an isolated environment:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install '.[mcp]'
+server-handbook --help
+```
+
+To obtain the source first:
+
+```bash
+git clone https://github.com/zzy1136660162/server-handbook.git
+cd server-handbook
+```
+
+On Windows activate `.venv\Scripts\Activate.ps1`, or call `.venv\Scripts\python.exe` directly. For an installed application with pipx, use `pipx install '.[mcp]'` from this checkout or install a supplied local wheel with the MCP extra. There is no npm wrapper and no second runtime.
+
+## Start a workspace
+
+```bash
+# Default is a preview: no directories or files are created.
+server-handbook init --workspace /srv/workspace
+server-handbook init --workspace /srv/workspace --apply
+cd /srv/workspace
+server-handbook handoff
+server-handbook project new demo --name 'Demo application' --kind compose
+server-handbook project new demo --name 'Demo application' --kind compose --apply
+```
+
+The generated declaration is `projects/demo/deploy/registry/demo.json`. It starts as `prepared`. Add the actual Compose project, service, files, ports, data references, and optional HTTP checks. Review the project README and existing rules. Preparation does not deploy an application.
+
+```bash
+server-handbook register /srv/workspace/projects/demo/deploy/registry/demo.json \
+  --note 'Initial reviewed deployment declaration; service not yet started'
+server-handbook plan demo --action up
+server-handbook apply demo --action up --expect-revision 1 \
+  --note 'Start the reviewed demo service and run its declared checks'
+server-handbook operations --service demo
+server-handbook doctor
+```
+
+Use `show demo` to read the current revision instead of copying the example number for an existing service. `apply` automatically retains real execution/check results and refreshes the managed README block. A process check alone is not business acceptance; configured HTTP probes are recorded separately.
+
+## Adopt an existing project
+
+Configure additional roots during initialization. Existing source, data and runtime directories are not moved:
+
+```bash
+server-handbook init --workspace /srv/workspace --project-root /opt/apps --apply
+server-handbook --config /srv/workspace/.server-handbook/config.json adopt \
+  --home /opt/apps/example --id example --name 'Existing application' --kind compose \
+  --compose-file /opt/apps/example/compose.yaml \
+  --compose-project example --compose-service web
+```
+
+Review the preview, then repeat with `--apply`. Adoption prepares files and instructions; registration is explicit. Existing declarations are never silently replaced. `discover` produces unconfirmed candidates without reading configuration values or auto-registering containers.
+
+## One source for each kind of information
+
+- `<service-home>/deploy/registry/<id>.json`: the editable service declaration.
+- `<workspace>/.server-handbook/config.json`: host name, directory roots and records location.
+- `<records-dir>/state.sqlite3`: registered snapshots/history and managed operation receipts, committed transactionally.
+- `AGENTS.md` and service `README.md`: human/agent guidance; generated content stays between `server-handbook` markers.
+- Runtime observations: queried on request, timestamped, and distinct from declarations and old receipts.
+
+SQLite state is local application metadata, not an application business database. It needs no MySQL, cloud account, server daemon, or model API key. The tool never starts an LLM itself.
+
+## MCP
+
+```bash
+server-handbook-mcp --config /srv/workspace/.server-handbook/config.json
+```
+
+The default interface is read-only stdio. Configure the client to launch this command, locally or through your existing SSH connection. Installing the server alone does not enroll every AI client automatically. `--allow-write` explicitly adds only registration and managed apply tools; it does not expose an arbitrary shell. See [MCP setup](docs/mcp.md).
+
+## What is recorded
+
+Managed operations record their plan and input hashes before commands execute, then save bounded step outcomes, actual check scope, status, timestamps, and documentation status. A service can have only one active managed operation. Failed preflight/commands/checks remain failed; interrupted work stays visible and is never automatically replayed.
+
+```bash
+server-handbook operation OPERATION_ID
+server-handbook recover OPERATION_ID --note 'Reviewed abandoned work; inspect live state before a fresh plan'
+```
+
+Recovery refuses a live owner and marks abandoned work interrupted; it neither rolls back external effects nor repeats commands. Compose operations manage the named service with dependencies left to the existing deployment process. No `down`, volume deletion, automatic database initialization, generic shell tool, or global privileged daemon is provided.
+
+Direct shell changes outside this tool are not fully attributable. Source drift may be detected later, but the tool cannot reconstruct every change or its purpose. A registered `deployed` state is not proof of current health. Paths in `secret_refs` are references, not a channel for returning credentials.
+
+## Develop and build
+
+```bash
+python -m pip install -e '.[mcp,dev]'
+python -m pytest
+python -m build
+```
+
+Most service-runner tests use isolated temporary workspaces and mocked commands; real loopback HTTP and stdio MCP tests are included. The optional Docker integration test is explicitly enabled with `SERVER_HANDBOOK_DOCKER_TESTS=1`; it uses only its own unique project and cleans it up. See [verification](docs/verification.md) for the checks actually performed and their limits.
+
+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). License: [MIT](LICENSE).

server_handbook-0.1.0/README.md

@@ -0,0 +1,114 @@
+# Server Handbook
+
+Server context, deployment registration, and tracked operations for humans and AI agents.
+
+[中文说明](README.zh-CN.md) · [Architecture](docs/architecture.md) · [CLI reference](docs/cli.md) · [MCP setup](docs/mcp.md)
+
+[Source](https://github.com/zzy1136660162/server-handbook) · [Report an issue](https://github.com/zzy1136660162/server-handbook/issues) · [PyPI publishing guide](docs/pypi-publishing.zh-CN.md)
+
+Server Handbook gives a new agent a predictable place to start, records where services live, and saves actual results from managed Compose/systemd actions. Existing projects can stay in their current directories. Manual README and AGENTS content outside marked blocks is preserved.
+
+**Status:** 0.1.0 alpha. The source and local distributions are usable; this project has not been published to PyPI. Core commands use only the Python standard library. MCP is an optional extra. Service execution targets Linux/Compose; clients and registry operations are portable.
+
+## Install from this checkout
+
+Python 3.11 or newer is required. Use an isolated environment:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install '.[mcp]'
+server-handbook --help
+```
+
+To obtain the source first:
+
+```bash
+git clone https://github.com/zzy1136660162/server-handbook.git
+cd server-handbook
+```
+
+On Windows activate `.venv\Scripts\Activate.ps1`, or call `.venv\Scripts\python.exe` directly. For an installed application with pipx, use `pipx install '.[mcp]'` from this checkout or install a supplied local wheel with the MCP extra. There is no npm wrapper and no second runtime.
+
+## Start a workspace
+
+```bash
+# Default is a preview: no directories or files are created.
+server-handbook init --workspace /srv/workspace
+server-handbook init --workspace /srv/workspace --apply
+cd /srv/workspace
+server-handbook handoff
+server-handbook project new demo --name 'Demo application' --kind compose
+server-handbook project new demo --name 'Demo application' --kind compose --apply
+```
+
+The generated declaration is `projects/demo/deploy/registry/demo.json`. It starts as `prepared`. Add the actual Compose project, service, files, ports, data references, and optional HTTP checks. Review the project README and existing rules. Preparation does not deploy an application.
+
+```bash
+server-handbook register /srv/workspace/projects/demo/deploy/registry/demo.json \
+  --note 'Initial reviewed deployment declaration; service not yet started'
+server-handbook plan demo --action up
+server-handbook apply demo --action up --expect-revision 1 \
+  --note 'Start the reviewed demo service and run its declared checks'
+server-handbook operations --service demo
+server-handbook doctor
+```
+
+Use `show demo` to read the current revision instead of copying the example number for an existing service. `apply` automatically retains real execution/check results and refreshes the managed README block. A process check alone is not business acceptance; configured HTTP probes are recorded separately.
+
+## Adopt an existing project
+
+Configure additional roots during initialization. Existing source, data and runtime directories are not moved:
+
+```bash
+server-handbook init --workspace /srv/workspace --project-root /opt/apps --apply
+server-handbook --config /srv/workspace/.server-handbook/config.json adopt \
+  --home /opt/apps/example --id example --name 'Existing application' --kind compose \
+  --compose-file /opt/apps/example/compose.yaml \
+  --compose-project example --compose-service web
+```
+
+Review the preview, then repeat with `--apply`. Adoption prepares files and instructions; registration is explicit. Existing declarations are never silently replaced. `discover` produces unconfirmed candidates without reading configuration values or auto-registering containers.
+
+## One source for each kind of information
+
+- `<service-home>/deploy/registry/<id>.json`: the editable service declaration.
+- `<workspace>/.server-handbook/config.json`: host name, directory roots and records location.
+- `<records-dir>/state.sqlite3`: registered snapshots/history and managed operation receipts, committed transactionally.
+- `AGENTS.md` and service `README.md`: human/agent guidance; generated content stays between `server-handbook` markers.
+- Runtime observations: queried on request, timestamped, and distinct from declarations and old receipts.
+
+SQLite state is local application metadata, not an application business database. It needs no MySQL, cloud account, server daemon, or model API key. The tool never starts an LLM itself.
+
+## MCP
+
+```bash
+server-handbook-mcp --config /srv/workspace/.server-handbook/config.json
+```
+
+The default interface is read-only stdio. Configure the client to launch this command, locally or through your existing SSH connection. Installing the server alone does not enroll every AI client automatically. `--allow-write` explicitly adds only registration and managed apply tools; it does not expose an arbitrary shell. See [MCP setup](docs/mcp.md).
+
+## What is recorded
+
+Managed operations record their plan and input hashes before commands execute, then save bounded step outcomes, actual check scope, status, timestamps, and documentation status. A service can have only one active managed operation. Failed preflight/commands/checks remain failed; interrupted work stays visible and is never automatically replayed.
+
+```bash
+server-handbook operation OPERATION_ID
+server-handbook recover OPERATION_ID --note 'Reviewed abandoned work; inspect live state before a fresh plan'
+```
+
+Recovery refuses a live owner and marks abandoned work interrupted; it neither rolls back external effects nor repeats commands. Compose operations manage the named service with dependencies left to the existing deployment process. No `down`, volume deletion, automatic database initialization, generic shell tool, or global privileged daemon is provided.
+
+Direct shell changes outside this tool are not fully attributable. Source drift may be detected later, but the tool cannot reconstruct every change or its purpose. A registered `deployed` state is not proof of current health. Paths in `secret_refs` are references, not a channel for returning credentials.
+
+## Develop and build
+
+```bash
+python -m pip install -e '.[mcp,dev]'
+python -m pytest
+python -m build
+```
+
+Most service-runner tests use isolated temporary workspaces and mocked commands; real loopback HTTP and stdio MCP tests are included. The optional Docker integration test is explicitly enabled with `SERVER_HANDBOOK_DOCKER_TESTS=1`; it uses only its own unique project and cleans it up. See [verification](docs/verification.md) for the checks actually performed and their limits.
+
+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). License: [MIT](LICENSE).

server_handbook-0.1.0/README.zh-CN.md

@@ -0,0 +1,106 @@
+# Server Handbook · 服务器工作手册
+
+让人和 AI 从固定入口接手服务器，按约定维护项目，并为通过工具执行的变更自动留下实际记录。
+
+[English](README.md) · [架构与数据归属](docs/architecture.md) · [完整命令](docs/cli.md) · [MCP 接入](docs/mcp.md)
+
+[GitHub 源码](https://github.com/zzy1136660162/server-handbook) · [提交 Issue](https://github.com/zzy1136660162/server-handbook/issues) · [发布到 PyPI](docs/pypi-publishing.zh-CN.md)
+
+当前为 **0.1.0 Alpha**，已提供源码和本地构建包，尚未发布到 PyPI。适合个人开发者、小团队、自托管服务器维护者。现有项目可以保留原来的位置；工具保留 README、AGENTS 中人工编写的内容。
+
+## 安装
+
+需要 Python 3.11 以上。进入本项目目录，使用独立环境安装：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install '.[mcp]'
+server-handbook --help
+```
+
+Windows 可使用 `.venv\Scripts\Activate.ps1`，也可直接调用环境内的 Python。已安装 pipx 时，可以从源码目录执行 `pipx install '.[mcp]'`。基础 CLI 没有第三方依赖，MCP 是可选附加功能。
+
+源码可先从 GitHub 获取：
+
+```bash
+git clone https://github.com/zzy1136660162/server-handbook.git
+cd server-handbook
+```
+
+仓库公开，欢迎提 Issue 或通过 Fork 提交 PR。普通访客不能直接推送或合并到原仓库；是否采纳由维护者决定。
+
+## 第一次使用
+
+```bash
+# 默认只预览；加 --apply 才创建目录和工具文件。
+server-handbook init --workspace /srv/workspace
+server-handbook init --workspace /srv/workspace --apply
+cd /srv/workspace
+server-handbook handoff
+server-handbook project new demo --name '演示项目' --kind compose --apply
+```
+
+新项目生成 `README.md`、`AGENTS.md`、`src/deploy/config/data/logs/docs` 的说明，以及 `deploy/registry/demo.json`。数据目录顶层可以放说明，数据库真实存储应使用 `data/store` 等程序专用目录；工具不会向现有程序存储目录塞 README。
+
+生成的声明默认 `prepared`，不表示已部署。填写实际 Compose 文件、project、service、端口、数据位置和需要执行的 HTTP 检查后，再登记和部署：
+
+```bash
+server-handbook register /srv/workspace/projects/demo/deploy/registry/demo.json \
+  --note '首次登记已核对的部署声明；尚未执行启动'
+server-handbook plan demo --action up
+server-handbook apply demo --action up --expect-revision 1 \
+  --note '启动已核对的服务并执行声明中的检查'
+server-handbook operations --service demo
+server-handbook doctor
+```
+
+已有记录先用 `show demo` 查当前 revision，不能照抄示例中的 `1`。登记失败不会覆盖旧快照；部署失败会保留失败凭条，CLI 返回非零退出码。执行检查、保存操作记录和刷新文档均由工具完成，不依赖 AI 最后记得手写总结。
+
+## 接入原有项目
+
+初始化时用重复的 `--project-root`、`--service-root` 声明实际根目录，用 `--records-dir` 指定台账位置。配置保存在工作区 `.server-handbook/config.json`。已有配置不同则拒绝覆盖，不会因重跑 init 改写目录规划。
+
+```bash
+server-handbook --config /srv/workspace/.server-handbook/config.json adopt \
+  --home /opt/apps/example --id example --name '已有项目' --kind compose \
+  --compose-file /opt/apps/example/compose.yaml \
+  --compose-project example --compose-service web
+```
+
+先检查预览，再加 `--apply`。`adopt` 不搬动源代码或数据，不自动启动服务，也不自动把候选变成已验证部署。`discover` 只读发现常见 Compose 文件和容器候选，用途、归属、备份方式等仍需核实。
+
+`project new --profile generic|python|node|java` 提供不同开发指导，不生成整套业务框架；已有项目自己的规范和用户当前指令优先。
+
+## 信息登记在哪里
+
+| 信息 | 位置 |
+| --- | --- |
+| 固定接手入口 | `<workspace>/AGENTS.md`、`README.md` |
+| 主机目录配置 | `<workspace>/.server-handbook/config.json` |
+| 服务声明源文件 | `<service-home>/deploy/registry/<id>.json` |
+| 已登记快照、历史、实际操作凭条 | `<records-dir>/state.sqlite3` |
+| 服务的人读维护说明 | 服务声明中的 `readme` 路径 |
+
+声明、现场观察和历史凭条分开。`state=deployed` 表示登记声明，当前是否运行用现场查询判断；“进程已运行”与“HTTP 检查通过”也分别记录。没有配置业务检查时，会明确标为进程检查，不能据此宣称完整业务验收通过。
+
+## AI 接入和中断恢复
+
+MCP 与 CLI 使用同一套核心：
+
+```bash
+server-handbook-mcp --config /srv/workspace/.server-handbook/config.json
+```
+
+默认只读。客户端需要单独配置启动命令；安装服务器端程序不会让所有 AI 客户端自动接入。按需添加 `--allow-write` 后，仅开放登记和受管理操作，不提供任意 shell。可分发的 Skill 位于 `src/server_handbook/assets/skills/server-handbook/`，安装后可用 `server-handbook skill export 目标目录 --apply` 导出。SSH 登录提示示例见 [MCP 文档](docs/mcp.md)，本包安装不会自动修改 SSH。
+
+```bash
+server-handbook operation 操作ID
+server-handbook recover 操作ID --note '已检查中断位置，下一步先核对现场'
+```
+
+操作开始前会落盘；中断后保留进行中记录。`recover` 拒绝仍在运行的操作，将已无执行者的操作标为中断，不自动重放，也不回滚外部副作用。通过普通 SSH 绕过工具修改时，只能尽量发现漂移，不能保证还原修改者和原因。
+
+Compose 只操作明确登记的 service；依赖服务需要预先启动。不会删除卷、重装系统、重新初始化数据库或启动全局 root 守护进程。
+
+验证范围见 [验证记录](docs/verification.md)。开源贡献见 [CONTRIBUTING.md](CONTRIBUTING.md)，许可证为 [MIT](LICENSE)。