kdletters
2bdee990a2
- dev-port.mjs 新增 resolveAgcAdminWebEndpoint：后台 Web 端口按 Linux 用户端口段 start + 3、非 Linux 优先 3102 解析，ADMIN_WEB_PORT 可显式指定，并把已解析的 AGC Vite 端口列为保留端口 - start-dev-stack.mjs 随 AGC 一起拉起 apps/admin-web（AGC_DEV_ADMIN_WEB=0 关闭）：与 AGC Vite 一样由启动器直接持有并纳入信号与退出收束，不走会整体重写 .app/dev-stack.json 的 dev:admin-web - start-dev-stack.mjs 新增启动汇总行，一次给出前端、后端、后台、数据库与 bgfilter-worker 的实际地址，端口漂移后以该行为准 - start-dev-stack.mjs 端口归属探测改用 netstat -ano 取端口到 PID、.NET Process 读可执行文件路径，仅在核对 SpacetimeDB --data-dir 归属时按 PID 取命令行并做 5 分钟 TTL 缓存：本机实测单轮探测由约 43 秒降到 0.37 秒，agc:serve 的 starting backend stack 到 backend ready 由约 80 秒降到 16.7 秒 - 后台 Web 端口解析或启动失败只告警，不阻断也不连带停止 AGC 客户端与配套后端 - tests/dev-port.test.ts、tests/start-dev-stack.test.ts 补充用例覆盖后台 Web 端口解析与严格占用、失败软化、启动汇总、netstat 探测脚本与命令行缓存失效 - docs/【开发运维】与 docs/technical 同步 AGC 开发态启动口径，pitfalls.md 记录 WMI 慢速探测的实测数据、netstat 改法与 PID 取最后一列的易错点
项目记忆目录
本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。.codex/ 只放 Codex 工具资源，不作为项目知识库。
当前结构
docs/project-memory/
├─ README.md
├─ shared-memory/
│ ├─ project-overview.md
│ ├─ team-conventions.md
│ ├─ development-workflow.md
│ ├─ document-map.md
│ ├─ decision-log.md
│ ├─ pitfalls.md
│ ├─ handoff-template.md
│ └─ 【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md
├─ plans/ # 仅限正在执行的短期计划
└─ todos/ # 仅限仍开放且有退出条件的事项
使用原则
- 开发前先读
AGENTS.md；复杂任务再读 Agent 执行准则、共享记忆和任务对应的当前专题文档。 - 稳定架构、接口、流程和排障边界写入
shared-memory/；同一事实只保留一个当前口径，细节放在权威专题文档。 plans/只保存正在执行、具有明确剩余项和验收门禁的计划；完成或作废后立即删除，稳定结论融合进当前专题或共享记忆。todos/只保存真实开放、有人接手即可执行的事项；每项应写明状态、下一决策点和关闭条件。已退役对象不保留未来 TODO。- 分支、提交、测试轮次和阶段流水账不进入长期记忆；需要追溯时使用 Git 历史。
- 若本目录与代码或最新
docs/冲突，以代码和最新专题为准，并在同次变更中修正记忆。 - 禁止写入个人配置、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
RAG 索引
本目录是本地 RAG 的高权重索引源，但检索结果只作为候选上下文。索引脚本位于 scripts/rag/；运行时依赖和 .rag/ 数据默认不安装、不提交，启用前需先征得用户确认。