From babfbb1534506cd3f4653fff8b0aed815daef7f7 Mon Sep 17 00:00:00 2001 From: ila Date: Fri, 21 Aug 2026 10:34:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=B0=E5=BD=95=20Windows=20?= =?UTF-8?q?=E5=90=AF=E5=8A=A8=E8=84=9A=E6=9C=AC=E6=B5=81=E7=A8=8B=20(#14)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/00-project-profile.md | 11 ++++--- docs/04-local-development-and-verification.md | 29 +++++++++++++++++-- 2 files changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/00-project-profile.md b/docs/00-project-profile.md index f8fb4fb..4f584d6 100644 --- a/docs/00-project-profile.md +++ b/docs/00-project-profile.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Project-Profile wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Project-Profile.- -wiki_revision: 662746817d09f4d182c6cf6db71e963d330141e8 -synchronized_at: 2026-08-20T15:04:43Z +wiki_revision: 233014296f1a555f1e223cbbeeedd5a974b767ca +synchronized_at: 2026-08-21T02:32:36Z # 项目档案 @@ -106,7 +106,7 @@ synchronized_at: 2026-08-20T15:04:43Z ## 常用命令 -所有命令默认从仓库根目录执行。Go 骨架、配置、迁移和种子命令已由 #6 落地；HTTP 服务仍需等待对应实现工单。 +所有命令默认从仓库根目录执行。Windows 本地开发优先使用 #14 提供的受管启动脚本；脚本只封装已有构建与运行入口，不执行迁移、AutoMigrate 或 seed。 | 用途 | 命令 | 预期结果 | |---|---|---| @@ -119,7 +119,9 @@ synchronized_at: 2026-08-20T15:04:43Z | 静态检查 | `go vet ./...` | 无输出 | | 数据库迁移 | `migrate -path migrations -database "$CHORUS_MIGRATE_URL" up` | 迁移版本前进且无错误 | | 幂等种子 | `go run ./cmd/chorus-seed` | 只输出完成状态，不输出凭据 | -| 启动用户端（#11 后可用） | `go run ./portal` | 当前 #6 仅校验配置并退出；#11 才监听 HTTP | +| 启动用户端 | `scripts\chorus-dev.bat start` | 后台启动并检查 `/login`，不执行迁移或 seed | +| 查看本地进程 | `scripts\chorus-dev.bat status` | 显示受管 portal 和 mock 的状态、PID 与日志位置 | +| 停止本地进程 | `scripts\chorus-dev.bat stop` | 只停止脚本记录且路径匹配的进程 | ## 目录边界 @@ -134,6 +136,7 @@ synchronized_at: 2026-08-20T15:04:43Z | `docs/` | 核心长期文档的 Wiki 只读镜像 | 人工直接维护的最终事实 | | `docs/task/` | 人工按需导出的任务归档快照 | 讨论过程和默认自动导出 | | `prototypes/` | 按工单/版本保存 HTML 审核快照 | 凭据、个人信息、生产数据 | +| `scripts/` | Chorus 本地开发与运行辅助脚本 | DevHarness 工具、凭据和生产数据 | | `dev_scripts/` | DevHarness 工具 | 产品业务脚本 | | `tests/` | Harness 测试；Go 测试与代码同目录 | 生产数据 | diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 9381eab..96357d3 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.- -wiki_revision: 075e82a07b58c105c46d7fbcfb22d8ed6d8f97f8 -synchronized_at: 2026-08-20T16:45:23Z +wiki_revision: bf8347d2ea78ebb91e0e1a9db53b80e53b9065a0 +synchronized_at: 2026-08-21T02:32:51Z # 本地开发与验证 @@ -142,7 +142,15 @@ go-admin AutoMigrate 不进入以上标准流程。如确需对照固定提交 MVP-0 不开放注册。使用可重复、不会在日志输出密钥的种子命令建立测试用户、默认 prompt template、Provider 和 ProviderModel。默认先连接 mock HTTP 上游，覆盖文本、图片、429、5xx、超时、连接错误、400、401 和内容策略拒绝。 真实 Provider 的连通性检查只能由操作者明确触发一次低成本请求，并核对审计与冷却；不能作为自动测试或反复调试方式。 -本地 mock 协议服务可单独启动，用于 curl 或协议调试： +本地 mock 协议服务可单独启动，用于 curl 或协议调试。Windows 推荐通过受管启动脚本运行： + +```bat +scripts\chorus-dev.bat start-mock +``` + +脚本默认读取仓库外的 `D:\OPC\chorus-tools\chorus-test.env.ps1`，也可把其他可信环境文件作为带引号的第二个参数传入。`start-mock` 只启动 mock 协议服务，不启动 worker，也不会放宽生产安全 Client 的 SSRF 规则。进程状态与日志保存在 `%LOCALAPPDATA%\Chorus\dev`。 + +前台调试仍可直接运行： ```powershell $env:CHORUS_MOCK_ADDR = "127.0.0.1:18080" @@ -155,6 +163,21 @@ go run ./cmd/chorus-mock-provider ### 5. 启动 portal（MVP-0） +Windows 本地开发优先使用仓库自带脚本： + +```bat +scripts\chorus-dev.bat start +scripts\chorus-dev.bat status +scripts\chorus-dev.bat restart +scripts\chorus-dev.bat stop +``` + +`start` 会校验环境文件、本地 MySQL TCP 连接和监听端口，构建临时可执行文件，在后台启动 portal，并检查 `/login`。重复启动不会创建第二个 portal；`restart` 只重启 portal；`stop` 只停止由脚本记录且可执行文件路径匹配的 portal 和 mock 进程。脚本不会执行迁移、GORM AutoMigrate、seed 或创建测试账号。 + +脚本默认读取仓库外的 `D:\OPC\chorus-tools\chorus-test.env.ps1`；也可把其他可信环境文件作为带引号的第二个参数传入，例如 `scripts\chorus-dev.bat start "D:\tools\chorus local.env.ps1"`。日志、PID 状态和临时可执行文件位于 `%LOCALAPPDATA%\Chorus\dev`。 + +需要在当前终端观察输出时，仍可运行： + ```powershell go run ./portal ```