From 8f114ebb7b5766403aa409d4a62ca1eba2fbb63f Mon Sep 17 00:00:00 2001 From: Explero <502024240091@smail.nju.edu.cn> Date: Wed, 15 Jul 2026 16:13:21 +0800 Subject: [PATCH] docs: add GitHub Pages manual site --- .github/workflows/docs.yml | 73 +++++++++++++++++++++++ .gitignore | 3 + docs/manual/assets/trellis.png | Bin 0 -> 990 bytes docs/manual/sources.md | 18 +++--- docs/manual/stylesheets/extra.css | 44 ++++++++++++++ docs/requirements.txt | 2 + mkdocs.yml | 93 ++++++++++++++++++++++++++++++ 7 files changed, 224 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/manual/assets/trellis.png create mode 100644 docs/manual/stylesheets/extra.css create mode 100644 docs/requirements.txt create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..2d67dfa --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,73 @@ +name: Deploy manual + +on: + push: + branches: + - main + paths: + - .github/workflows/docs.yml + - docs/manual/** + - docs/requirements.txt + - mkdocs.yml + pull_request: + branches: + - main + paths: + - .github/workflows/docs.yml + - docs/manual/** + - docs/requirements.txt + - mkdocs.yml + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + name: Build manual + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: docs/requirements.txt + + - name: Install documentation dependencies + run: python -m pip install --requirement docs/requirements.txt + + - name: Build documentation + run: mkdocs build --strict + + - name: Configure Pages + if: github.event_name != 'pull_request' + uses: actions/configure-pages@v5 + + - name: Upload Pages artifact + if: github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@v4 + with: + path: site + + deploy: + name: Deploy manual + needs: build + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index a8840fd..fcfceb7 100644 --- a/.gitignore +++ b/.gitignore @@ -187,3 +187,6 @@ tmp1/ .playwright-mcp .gitnexus .ace-tool/ + +# MkDocs build output +site/ diff --git a/docs/manual/assets/trellis.png b/docs/manual/assets/trellis.png new file mode 100644 index 0000000000000000000000000000000000000000..1f934d336e6767cbbe746b21c48e04cea8ad282e GIT binary patch literal 990 zcmeAS@N?(olHy`uVBq!ia0y~yVBW*Pz-Yq63=}B}ylw%c6p}rHd>I(3)EF2VS{N99 z0fib~Fff!FFfhDIU|_JC!N4G1FlSew4N$@*HNrE^*Ox&H$mU>RY|mt10kRl@SPF=N zrY~S*02$2)5?jColV#qsfEmVSGyy48_?f;5Nbv;tgt!9f3m5-oWY+)x|9?)se-)6= zSQ6wH%;50sMjD8dY3CLkD@$_|Nf5j-p%&RB#@!%DpkZOr*L`h0wNvc(H zQ7VvPFfuSQ(={;EH8Kk^Ft#!@vNAQ$HZZUBQ;SOya|_V*7+aZ`K`g0ge!m>3M-ZeZwIVak$~iwLzbLpMF*%jNkbgFlCs0xd zF6jzX;h&aPoLa(QWEL#FC>1Cx0hbNPtVqp?Z~to7kZb-6pD!B?Jr(a?ca<~V zwd9M5=Oh&<`nBiT*PoZ<-}}w|{Nv`#-yc5V27NDL`yTJOyMMc^{oPH^kABwP>zx>% zHRt*LpLzB>Cr`%>%0u4E{ag38^32)n-GAnunLG2^zDqy?REKc{o)xqapLonQakgAY7U-}b?- z>bzC)yz9H=^>KsuFYZlT?eeEjfo`ui?%VHcZ+&^z+2>&O nrTTHW!M%%np)vBszLs(OosXgnddsAuqW^>bP0l+XkK6Cj@% literal 0 HcmV?d00001 diff --git a/docs/manual/sources.md b/docs/manual/sources.md index 2ad33fe..e4fde52 100644 --- a/docs/manual/sources.md +++ b/docs/manual/sources.md @@ -14,18 +14,18 @@ ## 操作步骤 -- **S1**：[根说明](../../README.md)：项目定位、上游关系、试用建议和安全边界。 -- **S2**：[根包配置](../../package.json)、[命令包配置](../../packages/cli/package.json)、[核心包配置](../../packages/core/package.json)：版本、依赖、脚本和运行时要求。 -- **S3**：[命令入口](../../packages/cli/src/cli/index.ts)：正式主命令与参数；另以各命令 `--help`（帮助）实测核对。 -- **S4**：[初始化实现](../../packages/cli/src/commands/init.ts)、[更新实现](../../packages/cli/src/commands/update.ts)、[卸载实现](../../packages/cli/src/commands/uninstall.ts)、[工作流实现](../../packages/cli/src/commands/workflow.ts)。 -- **S5**：[工作流结构生成](../../packages/cli/src/configurators/workflow.ts)和 `packages/cli/src/templates/`（初始化模板目录）。 -- **S6**：[任务脚本](../../packages/cli/src/templates/trellis/scripts/task.py)及其 `common/`（公共脚本目录）。 +- **S1**：[根说明](https://github.com/Explero/Trellis-Hermes/blob/main/README.md)：项目定位、上游关系、试用建议和安全边界。 +- **S2**：[根包配置](https://github.com/Explero/Trellis-Hermes/blob/main/package.json)、[命令包配置](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/package.json)、[核心包配置](https://github.com/Explero/Trellis-Hermes/blob/main/packages/core/package.json)：版本、依赖、脚本和运行时要求。 +- **S3**：[命令入口](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/cli/index.ts)：正式主命令与参数；另以各命令 `--help`（帮助）实测核对。 +- **S4**：[初始化实现](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/commands/init.ts)、[更新实现](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/commands/update.ts)、[卸载实现](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/commands/uninstall.ts)、[工作流实现](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/commands/workflow.ts)。 +- **S5**：[工作流结构生成](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/configurators/workflow.ts)和 `packages/cli/src/templates/`（初始化模板目录）。 +- **S6**：[任务脚本](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/templates/trellis/scripts/task.py)及其 `common/`（公共脚本目录）。 - **S7**：`packages/cli/src/templates/trellis/hermes/`（科研配置、状态机、协议、角色和报告模板）。 - **S8**：`packages/cli/src/templates/trellis/scripts/hermes/`（科研记录、校验、运行、报告、服务和恢复脚本）。 -- **S9**：[平台注册表](../../packages/cli/src/types/ai-tools.ts)及平台配置器、技能、代理和钩子模板。 +- **S9**：[平台注册表](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/types/ai-tools.ts)及平台配置器、技能、代理和钩子模板。 - **S10**：`packages/cli/src/commands/channel/`（频道命令）和 `packages/core/src/channel/`（频道核心）。 -- **S11**：[会话记忆命令](../../packages/cli/src/commands/mem.ts)和 `packages/core/src/mem/`（会话记忆核心）。 -- **S12**：`packages/cli/test/`（命令与模板测试）、`packages/core/test/`（核心测试）和[科研预检脚本](../../packages/cli/scripts/hermes-preflight.js)。 +- **S11**：[会话记忆命令](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/src/commands/mem.ts)和 `packages/core/src/mem/`（会话记忆核心）。 +- **S12**：`packages/cli/test/`（命令与模板测试）、`packages/core/test/`（核心测试）和[科研预检脚本](https://github.com/Explero/Trellis-Hermes/blob/main/packages/cli/scripts/hermes-preflight.js)。 - **S13**：[上游官方中文手册](https://docs.trytrellis.app/zh)：参考“概览、安装、首个任务、工作原理、日常使用、高级内容、附录”的教学顺序；访问日期为 2026-07-14。本手册不是该网站的官方翻译或镜像，科研功能仍以 S1 至 S12 为准。 ## 预期结果 diff --git a/docs/manual/stylesheets/extra.css b/docs/manual/stylesheets/extra.css new file mode 100644 index 0000000..38f3fdb --- /dev/null +++ b/docs/manual/stylesheets/extra.css @@ -0,0 +1,44 @@ +:root { + --md-primary-fg-color: #166534; + --md-primary-fg-color--light: #15803d; + --md-primary-fg-color--dark: #14532d; + --md-accent-fg-color: #b45309; +} + +body, +.md-typeset { + letter-spacing: 0; +} + +.md-header { + border-bottom: 3px solid #d97706; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3 { + letter-spacing: 0; +} + +.md-typeset h1 { + color: #14532d; + font-weight: 700; +} + +[data-md-color-scheme="slate"] .md-typeset h1 { + color: #86efac; +} + +.md-typeset code { + border-radius: 4px; +} + +.md-typeset table:not([class]) th { + background: #f0fdf4; + color: #14532d; +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) th { + background: #1f2937; + color: #fde68a; +} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..65732f9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs==1.6.1 +mkdocs-material==9.7.6 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..02c8416 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,93 @@ +site_name: Trellis-Hermes 中文手册 +site_description: Trellis-Hermes 科研工作流的安装、使用、审计与维护手册 +site_url: https://explero.github.io/Trellis-Hermes/ +repo_url: https://github.com/Explero/Trellis-Hermes +repo_name: Explero/Trellis-Hermes +edit_uri: edit/main/docs/manual/ + +docs_dir: docs/manual +site_dir: site + +theme: + name: material + language: zh + logo: assets/trellis.png + favicon: assets/trellis.png + features: + - content.code.copy + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.sections + - navigation.top + - search.highlight + - search.suggest + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: green + accent: amber + toggle: + icon: material/brightness-7 + name: 切换到深色模式 + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: green + accent: amber + toggle: + icon: material/brightness-4 + name: 切换到浅色模式 + +plugins: + - search: + lang: zh + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.superfences + +extra_css: + - stylesheets/extra.css + +copyright: Copyright 2026 Trellis-Hermes contributors. Based on mindfold-ai/Trellis. + +nav: + - 首页: README.md + - 入门: + - 项目概览: 01-overview.md + - 安装: 02-installation.md + - 第一个科研任务: 03-first-research-task.md + - 工作原理: 04-how-it-works.md + - 项目与任务: + - 项目初始化: 05-project-setup.md + - 任务与规划: 06-tasks-and-planning.md + - 规范与上下文: 07-spec-and-context.md + - 科研记录: + - Hermes 记录: 08-hermes-records.md + - 实验配置: 09-experiments.md + - 运行与复查: 10-runs-and-replay.md + - 指标与比较: 11-metrics-and-comparison.md + - 报告与主张: 12-reports-and-claims.md + - 协作与维护: + - 工作代理与门禁: 13-workers-and-gates.md + - 工作流与平台: 14-workflows-and-platforms.md + - 频道与会话记忆: 15-channel-and-memory.md + - 更新、恢复与卸载: 16-update-recovery-and-uninstall.md + - 附录: + - 常用命令: appendix-a-cli-reference.md + - 目录参考: appendix-b-directory-reference.md + - 配置参考: appendix-c-configuration-reference.md + - 记录格式: appendix-d-record-schema.md + - 排障: appendix-e-troubleshooting.md + - 功能状态、安全与许可证: appendix-f-feature-status.md + - 事实来源: sources.md