From feaf9d36b48d1857f6945d9fc32e22c63974ad60 Mon Sep 17 00:00:00 2001 From: arno Date: Thu, 9 Apr 2026 09:29:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=B7=A5=E7=A8=8B?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=8F=8A=E6=8A=80=E6=9C=AF=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加本体论、ClaudeCode、Crablet、SpecKit 等技术文档 - 添加 AgentSkills、OpenClaw、Pencil、VSCode 等工具文档 - 添加 allenai 研究文档和 README 说明 --- 工程/AgentSkills.md | 1 + 工程/ClaudeCode.md | 188 +++++++++++++++++ 工程/Crablet.md | 2 + 工程/OpenClaw.md | 69 +++++++ 工程/Pencil.md | 5 + 工程/README.md | 124 ++++++++++++ 工程/SpecKit.md | 477 ++++++++++++++++++++++++++++++++++++++++++++ 工程/VSCode.md | 3 + 工程/allenai.md | 4 + 工程/本体论.md | 71 +++++++ 10 files changed, 944 insertions(+) create mode 100644 工程/AgentSkills.md create mode 100644 工程/ClaudeCode.md create mode 100644 工程/Crablet.md create mode 100644 工程/OpenClaw.md create mode 100644 工程/Pencil.md create mode 100644 工程/README.md create mode 100644 工程/SpecKit.md create mode 100644 工程/VSCode.md create mode 100644 工程/allenai.md create mode 100644 工程/本体论.md diff --git a/工程/AgentSkills.md b/工程/AgentSkills.md new file mode 100644 index 0000000..c96e005 --- /dev/null +++ b/工程/AgentSkills.md @@ -0,0 +1 @@ +# [Agent Skills](https://agentskills.io/home) \ No newline at end of file diff --git a/工程/ClaudeCode.md b/工程/ClaudeCode.md new file mode 100644 index 0000000..d5624d6 --- /dev/null +++ b/工程/ClaudeCode.md @@ -0,0 +1,188 @@ +# [Claude Code](https://code.claude.com/docs/zh-CN/quickstart) + +- Info + - [Claude Code Changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) + - [GLM-5](https://docs.bigmodel.cn/cn/guide/models/text/glm-5-turbo) + - [Claude Code GitHub](https://github.com/anthropics/claude-code) + - [Claude Code Plugins Directory](https://github.com/anthropics/claude-plugins-official.git) + - [Anthropic SDK Python](https://github.com/anthropics/anthropic-sdk-python) + - [Anthropic SDK TypeScript](https://github.com/anthropics/anthropic-sdk-typescript) + - [Anthropic SDK Java](https://github.com/anthropics/anthropic-sdk-java) + - [Claude Code CLI](https://docs.bigmodel.cn/cn/coding-plan/tool/claude) + - [Claude Code IDE 插件](https://docs.bigmodel.cn/cn/coding-plan/tool/claude-for-ide) + - [Happy Coder: Claude Code 的移动端和网页客户端 - 远程编程与 AI 助手](https://cc.deeptoai.com/docs/zh/tools/happy-mobile-claude-code-client) + - [飞书 + Claude Code：远程指挥电脑干活](https://wangqingping.top/blog/post/remoteClaudeCode) + - [cc-connect，十分钟帮你把 claude code 连接到微信，飞书，钉钉等等平台](https://juejin.cn/post/7611809566247616518) + - [OpenClaw 接入飞书](https://www.runoob.com/ai-agent/openclaw-feishu.html) +- GitHub + - [29471 Star | Claude Code Router](https://github.com/musistudio/claude-code-router) + - [14918 Star | Happy Coder: Mobile and Web Client for Claude Code & Codex](https://github.com/slopus/happy) Use Claude Code or Codex from anywhere with end-to-end encryption. + - [13775 Star | Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering.git) + - [10266 Star | Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) + - [03514 Star | CodePilot](https://github.com/op7418/CodePilot/blob/main/README_CN.md) + - [00877 Star | cc-connect](https://github.com/chenhg5/cc-connect) + - [00407 Star | OpencCode Manager](https://github.com/chriswritescode-dev/opencode-manager) + - [00212 Star | MetaBot](https://github.com/xvirobotics/metabot/blob/main/README_zh.md) + - [00012 Star | Remote Claude Code](https://github.com/qingpingwang/remote-claude-code) + +## 安装 + +```bash +# 安装 +cd +npm install -g @anthropic-ai/claude-code +claude --version + +# 配置 +npx @z_ai/coding-helper +curl -O "https://cdn.bigmodel.cn/install/claude_code_env.sh" && bash ./claude_code_env.sh +bash ./.devcontainer/cache/scripts/claude_code_env.sh + +# 创建快捷命令 +code ~/.local/bin/runcc.sh +#!/bin/bash +claude --ide --dangerously-skip-permissions --allow-dangerously-skip-permissions + +# 在 VS Code 成功进入 Claude Code 扩展 对话框后，在对话框输入 /config 进入设置，勾选 Disable Login Prompt 配置来关闭登录页面。 +``` + +```bash +# 1. 启用遥测 +export CLAUDE_CODE_ENABLE_TELEMETRY=1 + +# 2. 选择导出器（两者都是可选的 - 仅配置您需要的） +export OTEL_METRICS_EXPORTER=otlp # 选项：otlp、prometheus、console +export OTEL_LOGS_EXPORTER=otlp # 选项：otlp、console + +# 3. 配置 OTLP 端点（用于 OTLP 导出器） +export OTEL_EXPORTER_OTLP_PROTOCOL=grpc +export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 +``` + +```json +// 增加自定义设置 + "env": { + "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5-turbo", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1", + "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75" + }, +``` + +- 启用 agent teams + - Agent teams 默认禁用。 + - 通过将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量设置为 1 来启用它们，可以在你的 shell 环境中或通过 settings.json 进行： + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +## MCP, Plugin, Skill + +```bash +# 安装 SpecKit Specify CLI +uv tool install specify-cli --from git+https://github.com/github/spec-kit.git +# initialize in existing project +specify init . --ai claude +# Check installed tools +specify check + +# 安装 UI UX Pro Max globally CLI +npm install -g uipro-cli +uipro init --ai claude +``` + +```bash +### 安装 MCP +claude mcp add --transport stdio chrome-devtools -- npx -y chrome-devtools-mcp +claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest + +### 安装 Plugin, Skill +claude plugin marketplace add zai-org/zai-coding-plugins +claude plugin install glm-plan-usage@zai-coding-plugins +claude plugin install code-simplifier@claude-plugins-official --scope local/ +claude plugin uninstall code-simplifier --scope local +``` + +```bash +# 常用 Plugin + +# 66 +# https://github.com/zai-org/zai-coding-plugins +/plugin marketplace add zai-org/zai-coding-plugins +/plugin install glm-plan-usage@zai-coding-plugins +/glm-plan-usage:usage-query + +# 8.7k +# https://github.com/anthropics/claude-plugins-official +/plugin marketplace add anthropics/claude-plugins-official +/plugin install context7@claude-plugins-official +/plugin install superpowers@claude-plugins-official +/plugin install code-review@claude-plugins-official +/plugin install code-simplifier@claude-plugins-official +/plugin install ralph-loop@claude-plugins-official +/plugin install playwright@claude-plugins-official +/plugin install typescript-lsp@claude-plugins-official +/plugin install pyright-lsp@claude-plugins-official +/plugin install rust-analyzer-lsp@claude-plugins-official +/plugin install jdtls-lsp@claude-plugins-official +/plugin install gopls-lsp@claude-plugins-official + +# 77.6k +# https://github.com/github/spec-kit +uv tool install specify-cli --from git+https://github.com/github/spec-kit.git +specify init . --ai claude + +# 90.0k +# https://github.com/obra/superpowers +/plugin marketplace add obra/superpowers-marketplace +/plugin install superpowers@superpowers-marketplace + +# 60.89k +# https://github.com/nextlevelbuilder/ui-ux-pro-max-skill +/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill +/plugin install ui-ux-pro-max@ui-ux-pro-max-skill + +# 46.1k +# https://github.com/thedotmack/claude-mem +/plugin marketplace add thedotmack/claude-mem +/plugin install claude-mem + +# 30k +# https://github.com/wshobson/agents +# Claude Code Plugins: Orchestration and Automation +/plugin marketplace add wshobson/agents +# Essential development plugins +/plugin install python-development # Python with 16 specialized skills +/plugin install javascript-typescript # JS/TS with 4 specialized skills +/plugin install backend-development # Backend APIs with 3 architecture skills +# Infrastructure & operations +/plugin install kubernetes-operations # K8s with 4 deployment skills +/plugin install cloud-infrastructure # AWS/Azure/GCP with 4 cloud skills +# Security & quality +/plugin install security-scanning # SAST with security skill +/plugin install comprehensive-review # Multi-perspective code analysis +# Full-stack orchestration +/plugin install full-stack-orchestration # Multi-agent workflows + +# 12.9k +# https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering +/plugin marketplace add muratcankoylan/Agent-Skills-for-Context-Engineering +/plugin install context-engineering-fundamentals@context-engineering-marketplace +/plugin install agent-architecture@context-engineering-marketplace +/plugin install agent-evaluation@context-engineering-marketplace +/plugin install agent-development@context-engineering-marketplace +/plugin install cognitive-architecture@context-engineering-marketplace + +# 9.7k +# https://github.com/EveryInc/compound-engineering-plugin +/plugin marketplace add EveryInc/compound-engineering-plugin +/plugin install compound-engineering +``` diff --git a/工程/Crablet.md b/工程/Crablet.md new file mode 100644 index 0000000..3140cb2 --- /dev/null +++ b/工程/Crablet.md @@ -0,0 +1,2 @@ +# [Crablet](https://github.com/isLinXu/crablet) + diff --git a/工程/OpenClaw.md b/工程/OpenClaw.md new file mode 100644 index 0000000..6302ecd --- /dev/null +++ b/工程/OpenClaw.md @@ -0,0 +1,69 @@ +# [OpenClaw](https://github.com/openclaw/openclaw) + +## 信息 + +- [Moltbot Channels](https://docs.openclaw.ai/channels) +- wecom.ai.szis.com.cn +- glm api-key(moltbot ): 65a739c69f8549538f52b6878d2518cd.Rr979rpfuchGF1EL +- moltbot api-key: 35f9edf4b0e898b43ebf72be9280546746460954290ea5ac█ +- Gateway password: Arno2026!1522 +- [OpenClaw 的独特之处](https://zread.ai/openclaw/openclaw) + +## 部署 + +- [MoltBot(原moltbot)安装指南，接入企微、飞书、钉钉、QQ四大主流社交软件](https://www.cnblogs.com/runyuai/p/19547053) +- [玩转Lighthouse｜Moltbot一键秒级部署指南](https://cloud.tencent.com/developer/article/2624003) +- [云上Moltbot接入企业微信完全指南](https://cloud.tencent.com/developer/article/2625147) +- [云上Moltbot接入QQ完全指南](https://cloud.tencent.com/developer/article/2625097) +- [云上Moltbot接入飞书保姆级教程](https://cloud.tencent.com/developer/article/2625073) +- [云上Moltbot接入钉钉完全指南](https://cloud.tencent.com/developer/article/2625121) +- [Moltbot Connector](https://github.com/Tokeii0/moltbot_connector_qqbot) +- [让 Mac mini 一夜卖断货的开源项目，到底有多邪门？拆解 moltbot / Moltbot 的技术架构](https://juejin.cn/post/7599951933594484746) + +```bash +CONFIG_PATH=/workspace/arno/moltbot/.member/moltbot.json + +npm install -g moltbot@2026.1.27-beta.1 + +# 查看版本： +moltbot --version + +# 初始化配置信息 +moltbot onboard --install-daemon + +# 1. 安装插件 +moltbot plugins install @william.qian/simple-wecom + +# 2. 启用插件 +moltbot plugins enable simple-wecom + +# 3. 配置企业微信（必需） +moltbot config set channels.simple-wecom.corpid "ww1234567890abcdef" +moltbot config set channels.simple-wecom.corpsecret "your-corp-secret" +moltbot config set channels.simple-wecom.token "your-token" +moltbot config set channels.simple-wecom.encodingAESKey "your-aes-key" +moltbot config set channels.simple-wecom.enabled true + +# 4. 配置 Gateway +moltbot config set gateway.mode "local" +moltbot config set gateway.bind "0.0.0.0" +moltbot config set gateway.port 18789 + +# 5. 重启 Gateway +moltbot gateway status +moltbot gateway restart + +# 6. 验证 +moltbot channels status +``` + +```json + "wecom": { + "enabled": true, + "webhookPath": "/wecom", + "token": "填入创建企业微信机器人的页面，生成的Token", + "encodingAESKey": "填入创建企业微信机器人的页面，生成的encodingAESKey", + "receiveId": "", + "dm": { "policy": "pairing" } + } +``` diff --git a/工程/Pencil.md b/工程/Pencil.md new file mode 100644 index 0000000..8a2ec19 --- /dev/null +++ b/工程/Pencil.md @@ -0,0 +1,5 @@ +# [Pencil](https://marketplace.visualstudio.com/items?itemName=highagency.pencildev) + +```bash +ext install highagency.pencildev +``` diff --git a/工程/README.md b/工程/README.md new file mode 100644 index 0000000..8bc2f00 --- /dev/null +++ b/工程/README.md @@ -0,0 +1,124 @@ +# 工程 + +- [Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) +- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) +- [Claude Code 团队复合工程](https://www.youtube.com/watch?v=IDSAMqip6ms) +- [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) +- [我们如何使用 Codex 在 28 天内构建 Android 版 Sora](https://openai.com/zh-Hans-CN/index/shipping-sora-for-android-with-codex/) +- [Agent Skills Marketplace](https://skillsmp.com/) +- [Everything Claude Code : Claude Code 配置大全，开箱即用](https://zhuanlan.zhihu.com/p/1997978582736204425) +- [Everything Claude Code : The Shorthand Guide to Everything Claude Code 翻译](https://zhuanlan.zhihu.com/p/1998065856417124945) +- [Everything Claude Code : The Longform Guide to Everything Claude Code 翻译](https://zhuanlan.zhihu.com/p/1998068649773257278) + +## Git仓库 + +### Claude Code / AI Agent + +- [Superpowers](https://github.com/obra/superpowers) ⭐100k - Claude Code 超能力插件 +- [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) ⭐89k - Claude Code 资源大全 +- [Claude Code](https://github.com/anthropics/claude-code) ⭐80.3k - Anthropic 官方 Claude Code CLI 工具 +- [Spec Kit](https://github.com/github/spec-kit) ⭐78.7k - GitHub 规范工具包 +- [nanobot](https://github.com/HKUDS/nanobot) ⭐35k - HKUDS 自动化机器人框架 +- [Awesome DESIGN.md](https://getdesign.md/) ⭐34.8k - Copy a DESIGN.md into your project, tell your AI agent "build me a page that looks like this" and get pixel-perfect UI that actually matches. +- [OpenSpec](https://github.com/Fission-AI/OpenSpec) ⭐32.5k - OpenAPI 规范生成工具 +- [Page Agent](https://github.com/alibaba/page-agent.git) ⭐16.4k - 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。 +- [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) ⭐14k - 上下文工程的 Agent 技能 +- [Claude Plugins Official](https://github.com/anthropics/claude-plugins-official) ⭐13.1k - Claude 官方插件目录 +- [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) ⭐10.7k - Claude Code 复合工程插件 +- [VoltAgent](https://github.com/VoltAgent/voltagent) ⭐7.6k - VoltAgent 是一个端到端的 AI Agent 工程平台 +- [MasteringRAG](https://github.com/Steven-Luo/MasteringRAG) ⭐650 - RAG 掌握指南 + +### RAG / LLM 框架 + +- [n8n](https://github.com/n8n-io/n8n) ⭐180k - n8n 工作流自动化平台 +- [Dify](https://github.com/langgenius/dify) ⭐134k - Dify LLM 应用开发平台 +- [LangChain](https://github.com/langchain-ai/langchain) ⭐130k - LangChain 框架 +- [OpenWebUI](https://github.com/open-webui/open-webui) ⭐128k - Open WebUI 聊天界面 +- [RAGFlow](https://github.com/infiniflow/ragflow) ⭐75.6k - RAGFlow 开源 RAG 引擎 +- [Autogen](https://github.com/microsoft/autogen) ⭐55.9k - Microsoft Autogen 多智能体框架 +- [Flowise](https://github.com/FlowiseAI/Flowise) ⭐50.9k - Flowise 可视化 LLM 工作流 +- [LlamaIndex](https://github.com/run-llama/llama_index) ⭐47.8k - LlamaIndex RAG 框架 +- [crewAI](https://github.com/crewAIInc/crewAI) ⭐46.6k - crewAI 多智能体框架 +- [Quivr](https://github.com/QuivrHQ/quivr) ⭐39k - Quivr AI 知识管理 +- [SemanticKernel](https://github.com/microsoft/semantic-kernel) ⭐27.5k - Microsoft Semantic Kernel +- [FastGPT](https://github.com/labring/FastGPT) ⭐27.4k - FastGPT 知识库问答平台 +- [LangGraph](https://github.com/langchain-ai/langgraph) ⭐27k - LangGraph 状态图框架 +- [Haystack](https://github.com/deepset-ai/haystack) ⭐24.6k - Haystack NLP 框架 +- [Hindsight](https://github.com/vectorize-io/hindsight) ⭐5.3k - 向量检索后处理工具 +- [FlashRAG](https://github.com/RUC-NLPIR/FlashRAG) ⭐3.4k - FlashRAG 高效 RAG 框架 + +### 推理部署 + +- [Milvus](https://github.com/milvus-io/milvus) ⭐43.4k - Milvus 向量数据库 +- [FastChat](https://github.com/lm-sys/FastChat) ⭐39.4k - LMSYS 大模型系统组织 +- [SGLang](https://github.com/sgl-project/sglang) ⭐24.8k - SGLang 高效 LLM 调度语言 +- [TensorRT-LLM](https://github.com/NVIDIA/TensorRT-LLM) ⭐13.2k - NVIDIA TensorRT LLM 推理优化 +- [Xorbits Inference](https://github.com/xorbitsai/inference) ⭐9.1k - Xinference 模型推理平台 +- [CooperBench](https://github.com/cooperbench/CooperBench) ⭐11 - AI 模型性能基准测试 + +### SDK / 开发工具 + +- [Remotion](https://github.com/remotion-dev/remotion) ⭐40.1k - React 视频编程框架 +- [docker-credential-pass](https://github.com/docker/docker-credential-helpers) ⭐1.3k - Docker 凭证管理 +- [Anthropic SDK Java](https://github.com/anthropics/anthropic-sdk-java) ⭐259 - Anthropic Java SDK + +### 设计工具 + +- [Pencil](https://github.com/evolus/pencil) ⭐9.7k - 开源 UI 原型设计工具 + +### 资源集合 + +- [Jujutsu](https://github.com/jj-vcs/jj) ⭐27.1k - a version control system +- [gitbucket](https://github.com/gitbucket/gitbucket) ⭐9.4k - GitBucket Git 服务平台 +- [top-rss-list](https://github.com/weekend-project-space/top-rss-list) ⭐6k - 优质 RSS 源列表 +- [awesome-n8n](https://github.com/restyler/awesome-n8n) ⭐2.8k - n8n 社区节点资源 +- [WildCard](https://github.com/flmsdcj/WildCard) ⭐7 - GitHub WildCard 工具 + +### 原型 + +- [豆包](https://www.doubao.com/chat) + +## 参考文章 + +- [深度对比 vLLM、SGLang 与 llama.cpp，打通工程落地最后一公里](https://zhuanlan.zhihu.com/p/1991180964546778561) + - vLLM 解决了”如何在高并发下管好内存” + - SGLang 解决了”如何在高复用下省掉计算” + - llama.cpp 解决了”如何在普通硬件上跑得飞快” + - KTransformers 解决了”如何用有限显存跑大模型” +- [LMSYS Projects](https://lmsys.org/projects/) + +## 实践 + +- 提出需求，让 AI 来角色扮演，让它列出 N 个功能点，然后 AI 就会根据它的理解生成一个需求列表，接下来你再和 AI 对这些需求逐个打磨，这其实是一个高效冷启动的方法。 +- 在需求提出后，在规划阶段（Planning）不要给 AI 太具体的方案，而是让 AI 来生成方案，你只需要关注最终你想要的结果。 +- 提前告诉 AI 有哪些基础设施和环境的问题，让它少走弯路。 +- 提出需求的第一阶段要求 Agent 做的一些关键动作。 + - 比如无论接下来做什么，都要把计划和 todo 列表放在一个 work.md 或 todo.md 这类文件里。 + - 每完成一个阶段的工作，就把上一阶段的经验教训更新到 agents.md 里。 + - 当一个计划完成并且代码合并后，把这个工作的设计文档添加到项目的知识库中。 +- 在 Research 的过程中，告诉模型它拥有无限的预算和时间，尽可能充分地进行调研。 +- 如果模型有推理深度的参数，在这个阶段把它们全部调到最高级别。在这个阶段多烧一些 token、做好更好的规划、了解更多上下文，对后续的实现阶段会更有帮助。 +- 实现阶段要注意，要么你就让 AI 完全去做，要么你就完全自己做，千万别混着来，目前是倾向于完全零人工干预的模式效果更好。 +- 在测试和验收结果的阶段。你只要知道如何评估和测试你要的东西，AI 就一定能把东西给你做出来。 +- AI 不擅长集成测试、端到端测试。 +- 在完成大目标前，先和 AI 一起做一个方便的集成测试框架，并提前准备好测试的基础设施，收集和生成一些现成集成测试的用例，尽量一键能运行那种，这样在开发阶段就能事半功倍。 +- 关于如何使用这些测试的基础设施的信息，在正式开始前就固化在 agents.md 里。 +- 让 AI 帮你生成测试，但一定要告诉它一些生成的逻辑，标准和目的，另外就是千万不要把生成测试的 Context 和实际进行开发工作的 Agent 的 Context 混在一起。 +- 当前的 Coding Agent 在面对单一模块复杂度超过大约 5 万行代码之后，就开始很难把问题一次性解决掉，只要任务复杂度控制在这个阈值之下，在一个足够好的提示词驱动下，很多事情确实可以做到一次过。 + +/speckit.constitution +1. @docs/req.md @docs/tech.md @docs/ui.md 这3个文件是用户需求来源。 +2. 遵循敏捷开发方式。 +3. 项目的开发环境运行在 VS Code 的开发容器中，容器名是 `ai193`，对应的镜像是`arno:devcontainer-arno`，该镜像由 @.devcontainer/Dockerfile 构建。 +4. 项目根目录： `/home/arno/workspace/ai193`。 +5. 无论接下来做什么，都要把计划和 todo 列表放在 @docs/work.md 或者 @docs/todo.md 这类文件里。 +6. 每完成一个阶段的工作，就把上一阶段的经验教训更新到 @AGENTS.md 里。**注意：** @CLAUDE.md 是链接到 @AGENTS.md 文件的。 +7. 当进行 Research 的过程中，你拥有无限的预算和时间，尽可能充分地进行调研。 +8. 当单一模块复杂度超过大约 5 万行代码之后，需要拆分模块来实现。 + +/speckit.constitution +1. 当需要简化代码的时候，可以使用 `@"code-simplifier:code-simplifier (agent)"` +2. 当需要绘制架构图、甘特图、UML图、部署图、流程图、时序图、序列图等编码相关的图时，使用 'Mermaid' 格式 +3. 文档统一保存在 `@docs/` 目录，不要在其他地方保存 +4. shell脚本统一保存在 `@scripts/` 目录，不要在其他地方保存 +5. 执行任何命令前，必须先通过 `pwd` 确认当前工作目录是否是要执行命令所在的路径，避免路径错误 diff --git a/工程/SpecKit.md b/工程/SpecKit.md new file mode 100644 index 0000000..9c45d15 --- /dev/null +++ b/工程/SpecKit.md @@ -0,0 +1,477 @@ +# [GitHub Spec Kit](https://speckit.org/) + +| 指挥 | 描述 | 用途 | 脚本 | +|----------------|--------------------------------------------------|---------------------------------|---| +| 第一阶段 | | | | +| /constitution | 宪法：确立项目原则。制定项目管理原则和发展指南 | 先运行以建立项目标准 | | +| /specify | 规格：明确定义需求。定义你想构建的内容（需求和用户故事） | 关注“做什么”和“为什么”，而不是技术栈 | create-new-feature.sh | +| /clarify | 澄清：解决歧义。通过结构化提问澄清未明确的领域 | 除非明确跳过，否则必须先运行/plan | check-prerequisites.sh | +| 第二阶段 | | | | +| /plan | 规划：选择技术栈和架构。使用选定的技术栈制定技术实施计划 | 明确架构、框架和技术决策 | setup-plan.sh + update-agent-context.sh | +| /tasks | 任务：拆分成可作的项目。生成可执行的任务列表 | 将计划拆解为可执行的步骤 | check-prerequisites.sh | +| /analyze | 跨工件一致性与覆盖分析 | 跑过后，先跑/tasks/implement | check-prerequisites.sh | +| /implement | 实施：生成可工作代码。执行所有任务，按计划构建功能 | 根据规范生成可工作代码 | check-prerequisites.sh | +| 补充 | | | | +| /checklist | 根据用户需求生成当前功能的定制检查清单 | | check-prerequisites.sh | +| /taskstoissues | 将现有任务转化为基于现有设计产出的、具有依赖关系的可执行GitHub功能需求事项 | | check-prerequisites.sh | + +## ipass 使用 Spec Kit + +- 提前整理需求，创建 @/docs/specification.md +- 始终在分支开发，功能测试通过后合并到 trunk + +### 确立项目原则 constitution + +- 根据交互式或预设原则输入创建/更新项目章程，并保持所有关联模板的同步更新 + +```bash +/speckit.constitution +- Always Use Chinese in SpecKit, Specfiy, Claude Code +- SpecKit/Specfiy 的所有文档必须使用中文编写，包括但不限于：规格说明（spec.md）、实施计划（plan.md）、任务列表（tasks.md）、检查清单（checklists/*.md） +- 代码注释必须使用中文，变量和函数命名使用英文，但注释说明必须使用中文，错误提示信息必须使用中文，用户文档必须使用中文 +- 当需要简化代码的时候，可以使用 `@"code-simplifier:code-simplifier (agent)"` +- 当需要绘制架构图、甘特图、UML图、部署图、流程图、时序图、序列图等编码相关的图时，使用 'Mermaid' 格式 +- 在开发阶段，不要新启动数据库容器，使用现有的 'mysql8' 容器， 开发环境数据库用户 'root', 密码 'mysql_root_password'，如果新创建数据库，则新创建一个 mysql 账号来使用新数据库，如果 'mysql8' 容器不可用，提示用户手动启动 +- `@.member/arno.md` 是供 Arno Jin 个人开发 iPass 的笔记， AI Agent/Skills/Plugins/MCP/Commands 不应该从这个笔记文件读取数据 +- `@docs/UI.md` 是iPass项目界面设计方案 +- `@docs/specification.md` 是iPass项目需求文档 +- 文档统一保存在 `@docs/` 目录，不要在其他地方保存 +- shell脚本统一保存在 `@scripts/` 目录，不要在其他地方保存 +- 执行任何命令前，必须先通过 `pwd` 确认当前工作目录是否是要执行命令所在的路径，避免路径错误 +- 脚本文件必须在开头设置 `set -e` 并记录工作目录 +- 当需要简化代码时，优先使用 `@"code-simplifier:code-simplifier (agent)"` 代理 +- 所有 Markdown `.md` 文件必须使用 2 个空格作为缩进,而非制表符 (Tab) +- SpecKit/Specfiy 模板中的项目团队、负责人、OWNER 等占位符必须使用 `git config user.name` 获取的当前 Git 用户名填充，AI 助手在生成新文档时,必须自动查询 Git 配置并填充相关占位符，禁止使用硬编码的默认值（如 "作者姓名"、"待定" 等），如果 Git 配置未设置,必须提示用户先配置 Git 用户信息 +- 服务端不应该提供客户端设备注册API，而是应该通过 `ipass-cli device add --device-id --name "我的MacBook"` 命令，在服务端进行客户端设备注册 +- 所有 Python 代码必须通过 `pyright` 严格类型检查：在 pyproject.toml 中启用 `pyright` 严格模式；所有函数必须具有类型注解；禁止使用 `# type: ignore`，除非在代码注释中有明确说明；类型错误阻止提交和 PR；使用存根文件 (.pyi) 定义外部类型 + +# 要求 Specify 使用中文 +/speckit.constitution Always Use Chinese in speckit +# 执行后， Specify 已经分析了 CLAUDE.md 和 specification.md 的内容提取到了宪章中 + +# 避免读取临时文件内容 +/speckit.constitution speckit 不要读取和使用 @docs/arno.md 中的内容，这个文档是供开发者临时保存文本用的 + +# 约束行为 +/speckit.constitution 我发现创建的 @specs/001-ipass-platform/checklists/requirements.md 使用的是英文，在 SpecKit 中，不管在哪个阶段，都必须使用中文。 + +# 提供工具 +/speckit.constitution 当需要简化代码的时候，可以使用 @"code-simplifier:code-simplifier (agent)" +/speckit.constitution 当需要绘制架构图、甘特图、UML图、部署图、流程图、时序图、序列图等编码相关的图时，使用 Mermaid 格式 +/speckit.constitution 当需要绘制架构图时，使用 Mermaid 格式 +/speckit.constitution 统一使用国内镜像源： +1. Ubuntu 等系统使用 mirrors.tuna.tsinghua.edu.cn 镜像源 +2. npm 镜像 https://registry.npmmirror.com +3. pip 镜像 https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple +4. Node.js 镜像 https://npmmirror.com/mirrors/node +/speckit.constitution 不要启动单独的 mysql 容器，使用现有的 mysql8 容器， 用户 root, 密码 mysql_root_password，如果新创建数据库，则新创建一个 mysql 账号来使用新数据库 + +docker ps + ⎿ ⧉ Selected 1 lines from docker/volumes/mysql/docker-compose.yml in Visual Studio Code + ⎿ CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 2ef05ed5ff2b arno:mysql8 "docker-entrypoint.s…" 4 hours ago Up 4 hours (healthy) mysql8 + +/speckit.constitution 使用 @docs/ui.md 作为界面标准 +/speckit.constitution 结合 ui-ux-pro-max SKILLS 来生成界面 +/speckit.constitution 执行任何命令前，先确认当前路径是否是要执行命令所在的路径。避免路径错误。 +``` + +### 明确功能 specify + +- 根据自然语言描述创建/更新功能规格说明书 + +```bash +/speckit.specify 根据 @docs/specification.md 中的功能需求和非功能需求，开发ipass服务端和客户端。 +# 下一步操作 +# +# 规格已就绪，可以继续以下工作流： +# +# 1. 进入规划阶段: 运行 /speckit.plan 生成实施计划 +# 2. 需求澄清: 如有疑问可运行 /speckit.clarify +# 3. 任务生成: 规划完成后运行 /speckit.tasks 生成任务列表 +# +# 🔗 相关链接 +# +# - Pull Request: https://gitea.szis.dev/szisos/ipass/pulls/new/001-ipass-platform +# 需要在上述 Pull Request 做代码拉取的批准 +/speckit.specify 检查当前 @specs/001-ipass-platform/spec.md 是否符合要求 +/speckit.specify 根据 @docs/ui.md 检查是否要更新文档 +/speckit.specify 检查 @specs/1-ui-docs-update +/speckit.specify 检查 @specs/002-ui-docs-update/spec.md 中对 ui和ux的要求是否都体现到了 @specs/003-ipass-implementation/spec.md 对 ipass-client 的界面定义上.如果没有,请补充 +``` + +### 澄清存在歧义的问题 clarify + +- 通过提出最多5个针对性澄清问题，识别当前功能规格说明中的未明确项，并将答复内容编码回规格文档 + +```bash +/speckit.clarify 在 @.specify/memory/constitution.md 中使用了和 @docs/specification.md 不同的加密处理方式。根据 @/docs/encryption-analysis.md 的建议对 @.specify/memory/constitution.md 和 @docs/specification.md 进行调整。 +/speckit.clarify 检查 SpecKit 相关脚本文件是否完整，如果缺失，请补充。 +/speckit.clarify 5.1 服务端 API 中 ‘设备注册’ 对应的接口 /api/v1/device/register 不应该被客户端访问到，客户端设备注册是通过 ipass-server-cli 的命令来进行的。 +/speckit.clarify 执行 '/speckit.plan' 的时候，反馈缺少 'setup-plan.sh'，请补充 'setup-plan.sh'，并分析是否还存在其他确实的 SpecKit 相关脚本。 +/speckit.clarify 001-ipass-platform 内容已经合并到了 trunk ,请删除本地及远程的功能分支 001-ipass-platform。 +/speckit.clarify 在执行 '/speckit.analyze' 的时候，出现以下错误。请检查是否是因为生成的脚本 @.specify/scripts/bash/check-prerequisites.sh 编写存在问题 +Bash(.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks) + ⎿ Error: Exit code 1 + 未知参数: --require-tasks +/speckit.clarify 执行以下操作： +1. 删除 @.specify/scripts/bash/*.sh 。 +2. 复制原始的 SpecKit 脚本到 @.specify/scripts/bash/ 目录。 +3. 检查复制过来的脚本是否需要按照中文要求和项目要求进行调整。 +4. 完成上述3个任务后，在不破坏原始的 SpecKit 脚本功能的前提下，将脚本的注释和输出信息换成中文。 + +1. 创建 1-ui-docs-update 分支，切换到该分支 +2. 清空 tasks.md 中所有任务标记完成的标识 +``` + +### 规划 plan + +- 执行实施规划工作流，使用规划模板生成设计工件 + +```bash +/speckit.plan +# 实施计划写入文件 +# Read agent output aae9c8f +# ⎿ Error: File content (326.4KB) exceeds maximum allowed size (256KB). +# Please use offset and limit parameters to read specific portions of the file, or use the GrepTool to search for specific content. +``` + +### 拆分任务 task + +- 基于现有设计工件，生成可执行的、依赖关系排序的功能任务清单 task.md + +```bash +/speckit.tasks 生成详细任务列表 +# 现在规划阶段已经完成。让我总结一下当前的状态并准备开始实施： +# +# ✅ 规划阶段完成 +# +# 已完成的工作: +# +# 1. 规格文档 (specs/2-ipass-implementation/spec.md) +# - 功能规格定义了 6 个用户场景 +# - 从用户视角描述"是什么"和"为什么" +# 2. 技术设计 (specs/2-ipass-implementation/technical-design.md) +# - 完整技术栈定义 +# - 系统架构和接口规范 +# - 从开发视角描述"如何实现" +# 3. 实施计划 (docs/plan/2-ipass-implementation.md) +# - 技术上下文和宪章检查 +# - 关键里程碑和 Mermaid 甘特图 +# 4. 任务列表 (specs/2-ipass-implementation/tasks.md) +# - 87 个任务，覆盖 6 个用户场景 +# - 每个任务包含具体的文件路径和实施细节 +# - 标记了并行任务 [P] 和用户故事关联 [US1-US6] +# - 包含 MVP 范围定义 +# +# MVP 范围: Phase 1-4 + Phase 6 (US1) - 共 38 个任务 +# +# 下一步: 根据任务列表开始实施，从 Phase 1 (T001-T010) 开始： +# +# Phase 1: 设置阶段 +# - T001: 创建项目目录结构 ipass/ +# - T002-T009: [P] 并行创建各种模块和配置文件 +# - T010: 初始化 Alembic 迁移配置 +# +# 是否需要我开始执行任务 T001，创建项目的目录结构？ +``` + +### 分析文档中不一致的地方 analyze + +- 执行非破坏性跨工件一致性检查与质量分析（覆盖规格文档.md、计划文档.md及任务清单.md），于任务生成后实施 + +```bash +/speckit.analyze +# 下一步行动 +# +# 必须在 /speckit.implement 前解决： +# 1. [CRITICAL] A1: 统一设备注册机制描述 +# - 在 technical-design.md 第 237 行添加引用："详见 spec.md 第 13.1 节设计澄清记录" +# - 强调 CLI-only 方案，删除可能的歧义 +# 2. [HIGH] A2: 修正任务数量统计 +# - 更新 tasks.md 第 12 行："总任务数: 137" +# 3. [HIGH] A3: 统一加密算法描述 +# - 在所有文档中明确："AES-256-GCM (主) / XChaCha20-Poly1305 (备选，用于无硬件加速设备)" +# 4. [HIGH] A4: 统一 Argon2id 参数单位 +# - 统一为 "128MB"（而非 "128 * 1024"） +# 5. [HIGH] A5: 添加性能测试前提 +# - 更新 spec.md 3.2 节："在标准开发硬件（4GB RAM, 2 核 CPU）上，客户端本地操作 < 100ms" +# +# 建议在实施前解决： +# +# 6. [MEDIUM] A6-A10: 添加缺失的测试任务 +# - T138: 容量测试（10,000 条目） +# - T139: 性能基准测试（自动化） +# - T140: 渗透测试 +# 7. [MEDIUM] A11: 统一数据模型术语 +# - 建议：spec.md "操作日志（AuditLog）" → "同步日志（SyncLog）" +# +# 可选改进： +# +# 8. [LOW] A13-A15: 清理模糊性和重复 +# - 删除"直观的图形界面" +# - 验证 MySQL 容器路径 +# - 合并验收标准和任务 +/speckit.analyze +1. [CRITICAL] A1: 统一设备注册机制描述 中 technical-design.md 是设计为通过 cli 来使用，符合要求。可以增加引用："详见 spec.md 第 13.1 节设计澄清记录" +2. 针对发现的2、3、4、6、7问题，按照推荐的方式进行修复 +3. [HIGH] A5: 添加性能测试前提 中对性能的要求，可以不用处理。理由是本软件是一个人使用，存储的密码条数不多。请同步更新相关文档 +``` + +### 实施计划 implement + +- 执行实施计划，处理并完成 tasks.md 中定义的所有任务 + +```bash +/speckit.implement +# 建议的下一步 +# +# 1. 运行规格澄清: /speckit.clarify - 识别 spec.md 中需要澄清的领域 +# 2. 完善规格说明: 根据澄清结果更新 spec.md +# 3. 更新 checklist: 手动或重新生成 checklist 并标记完成项 +# 4. 验证 checklist: 确保所有 16 项都通过 +# 5. 重新运行实施: /speckit.implement 继续实施 +# +# 是否需要我帮助您运行 /speckit.clarify 来开始澄清流程？ + +/speckit.implement git 分支 2-ipass-implementation 已经合并到了 trunk 。执行实施计划，处理并完成 tasks.md 中定义的所有任务。 +# 好的,我了解了技术架构。现在让我开始实施。由于这是一个大型项目(137个任务),我将创建追踪并按阶段推进。 +# +# ✻ Compacting conversation… (ctrl+c to interrupt · ctrl+t to hide todos · 1m 18s · ↓ 425 tokens) +# ⎿ ☐ Phase 1: 设置阶段 (T001-T010) +# ☐ Phase 2: 基础设施层 (T011-T020) +# ☐ Phase 3: 服务端数据库层 (T021-T027) +# ☐ Phase 4: US1 首次设置 (T028-T038) +# ☐ Phase 5-15: 其他阶段 (T039-T137) + +/speckit.implement +1. 运行 uv pip install -r requirements.txt 安装依赖 +2. 运行 PYTHONPATH=/workspace/ipass && uv run python scripts/init_db.py 初始化数据库 +3. 继续 Phase 4 (US1 - 首次设置) 的实现 +/speckit.implement 继续实现 US1 GUI - 完整的图形界面 + +/speckit.implement 进行： +1. 测试：运行集成测试验证完整流程 +2. US2 实现：添加第二台设备的证书导入功能 +3. US3 实现：密码管理主界面（添加、查看、编辑密码） + + +/speckit.implement 参考 @specs/2-ipass-implementation/tasks.md 完成 US3（密码管理主界面），还需要实现： + +优先级高 + +1. 数据访问层 (client/core/database.py) +- PasswordEntryDAO: add, update, delete, get_all, search +- CategoryDAO: add, update, delete, get_all, get_tree +2. GUI 对话框 +- 添加密码对话框 (add_password.py) +- 查看密码对话框 (view_password.py) +- 编辑密码对话框 (edit_password.py) +3. 密码列表界面 (main_window.py 扩展) +- PasswordListView 显示列表 +- 搜索和过滤功能 +- 操作按钮布局 + +优先级中 + +4. 剪贴板功能 (client/gui/clipboard.py) +- 复制到剪贴板 +- 30秒后自动清空 +5. 同步功能 (client/core/sync.py 扩展) +- CRDT 操作记录 +- 同步客户端 +- 离线队列 + +优先级低 + +6. 服务端 API (US3 相关) +- FastAPI 应用初始化 +- 同步 API 路由 +- 设备验证中间件 + +完成高优先级任务后提交并推送代码 + +/ralph-loop:ralph-loop /speckit.implement @specs/2-ipass-implementation/tasks.md +``` + +### 开发 + +```bash +/speckit.implement 虽然任务标记为完成了,但实际代码功能上缺少很多功能.例如: +1. 不能添加分类 +2. 不能调整服务器设置 +3. 不能添加分类 +4. 不能在客户端和服务端同步数据 +5. UI界面不符合定义 +``` +/speckit.plan +```bash +/speckit.specify +弹出的确认框，现在是 'OK', 'Yes', 'No' 这样的英文按钮。 +改为 '确认', '取消' 两个按钮。 +检查一下其他界面、按钮是否还存在英文文字内容。 +/speckit.clarify +/speckit.plan +/speckit.tasks +/speckit.implement +``` + +```bash +# 004-ui-requirements-sync +/speckit.specify +1. 在登陆界面直接显示密码输入框、确定后进入管理界面，不需要点击“登陆”按钮弹出界面。同步调整“忘记密码” +2. 减少弹出窗口，在界面底部增加状态条，用于显示信息，或者在界面右上角显示浮动消息，过一段时间自动隐藏。 +3. 在程序设置界面修改主题为浅色、深色，没有效果。 +/speckit.plan 先提交代码,在开始执行 plan +/speckit.tasks +/speckit.implement +``` + +```bash +# 008-ux-message-bar-logo +/speckit.specify +1. 移除'界面右上角显示浮动消息'的功能 +2. 统一在打开窗口的底部增加消息栏，消息和提示在消息栏显示 +3. 在登陆界面显示LOGO +4. 界面宽度缩小后，搜索输入框和分类标题重叠了，修改限制 +/speckit.plan +/speckit.tasks +/speckit.implement +/speckit.implement +1. 运行单元测试验证功能 +2. 生成真实的 PNG LOGO +3. 编译 Qt 资源文件 +4. 提交代码并合并到 trunk + +/speckit.implement 分支 008-ux-message-bar-logo 上的以下4个功能请检查是没有实现还是没有正确的合并到 trunk +1. 移除'界面右上角显示浮动消息'的功能 +2. 统一在打开窗口的底部增加消息栏，消息和提示在消息栏显示 +3. 在登陆界面显示LOGO +4. 界面宽度缩小后，搜索输入框和分类标题重叠了，修改限制 + +/speckit.implement 服务端收到以下信息，但查看 ipass-db 没有数据 +INFO: 127.0.0.1:53380 - "GET /health HTTP/1.1" 200 OK +[2026-01-16 14:21:34] [INFO] [server] 收到同步请求: device_id=device-09ca8d9d-955b-427b-8fc1-cc5176886d15, crdt_ops数量=4 +[2026-01-16 14:21:34] [INFO] [server] 设备验证通过: device-09ca8d9d-955b-427b-8fc1-cc5176886d15 +[2026-01-16 14:21:34] [DEBUG] [server] 转换操作: update - entry_id=5899a457-d57e-4140-912b-3265508d8481, has_data=True +[2026-01-16 14:21:34] [DEBUG] [server] 转换操作: update - entry_id=cdb732e5-4452-4b14-83a8-97812429983a, has_data=True +[2026-01-16 14:21:34] [DEBUG] [server] 转换操作: update - entry_id=b998838a-b22c-4976-9f8a-e7be18832532, has_data=True +[2026-01-16 14:21:34] [DEBUG] [server] 转换操作: update - entry_id=c000cf35-3139-4c4e-ac8c-a6eb519017a6, has_data=True +[2026-01-16 14:21:34] [INFO] [server] 成功转换 4 个操作 +[2026-01-16 14:21:34] [WARNING] [server] 跳过更新操作(条目不存在): entry_id=5899a457-d57e-4140-912b-3265508d8481 +[2026-01-16 14:21:34] [WARNING] [server] 跳过更新操作(条目不存在): entry_id=cdb732e5-4452-4b14-83a8-97812429983a +[2026-01-16 14:21:34] [WARNING] [server] 跳过更新操作(条目不存在): entry_id=b998838a-b22c-4976-9f8a-e7be18832532 +[2026-01-16 14:21:34] [WARNING] [server] 跳过更新操作(条目不存在): entry_id=c000cf35-3139-4c4e-ac8c-a6eb519017a6 +[2026-01-16 14:21:34] [INFO] [server] 操作处理完成: 添加=0, 更新=0, 删除=0, 跳过=4 +[2026-01-16 14:21:34] [INFO] [server] 数据库提交成功 + +/speckit.implement 服务端收到以下信息，但查看 ipass-db 数据库，只同步了4条密码数据，目录数据，操作日志等都没有同步 +INFO: 127.0.0.1:52078 - "GET /health HTTP/1.1" 200 OK +[2026-01-16 14:26:30] [INFO] [server] 收到同步请求: device_id=device-09ca8d9d-955b-427b-8fc1-cc5176886d15, crdt_ops数量=4 +[2026-01-16 14:26:30] [INFO] [server] 设备验证通过: device-09ca8d9d-955b-427b-8fc1-cc5176886d15 +[2026-01-16 14:26:30] [DEBUG] [server] 转换操作: update - entry_id=5899a457-d57e-4140-912b-3265508d8481, has_data=True +[2026-01-16 14:26:30] [DEBUG] [server] 转换操作: update - entry_id=cdb732e5-4452-4b14-83a8-97812429983a, has_data=True +[2026-01-16 14:26:30] [DEBUG] [server] 转换操作: update - entry_id=b998838a-b22c-4976-9f8a-e7be18832532, has_data=True +[2026-01-16 14:26:30] [DEBUG] [server] 转换操作: update - entry_id=c000cf35-3139-4c4e-ac8c-a6eb519017a6, has_data=True +[2026-01-16 14:26:30] [INFO] [server] 成功转换 4 个操作 +[2026-01-16 14:26:30] [INFO] [server] UPDATE 创建新条目: entry_id=5899a457-d57e-4140-912b-3265508d8481 +[2026-01-16 14:26:30] [INFO] [server] UPDATE 创建新条目: entry_id=cdb732e5-4452-4b14-83a8-97812429983a +[2026-01-16 14:26:30] [INFO] [server] UPDATE 创建新条目: entry_id=b998838a-b22c-4976-9f8a-e7be18832532 +[2026-01-16 14:26:30] [INFO] [server] UPDATE 创建新条目: entry_id=c000cf35-3139-4c4e-ac8c-a6eb519017a6 +[2026-01-16 14:26:30] [INFO] [server] 操作处理完成: 添加=4, 更新=0, 删除=0, 跳过=0 +[2026-01-16 14:26:30] [INFO] [server] 数据库提交成功 +``` + +```bash +# 009-unified-logging +/speckit.specify 统一 ipass-server, ipass-server-cli, ipass-clinet 日志输出格式，并在每条日志前面显示时间，时间格式为：yyyy-MM-dd HH:MM:SS +/speckit.plan +/speckit.implement # 会自动执行 /speckit.tasks +/speckit.implement 日志格式不符合要求，如下[DEBUG] 、[网络检查]、[Toast] +[2026-01-16 14:10:57] [INFO] [client] Theme applied: system +[2026-01-16 14:10:57] [INFO] [client] Creating main window... +QMainWindowLayout::addItem: Please use the public QMainWindow API instead +[2026-01-16 14:10:57] [INFO] [client] Client started successfully +[DEBUG] 尝试加载证书: /home/arno/.ipass/data_certificate.enc +[DEBUG] 证书加载成功 +✓ 数据库迁移完成 +✓ 数据库迁移完成 +[网络检查] 正在连接: http://localhost:8088/health +[网络检查] 响应状态码: 200 +[网络检查] 正在连接: http://localhost:8088/health +[网络检查] 响应状态码: 200 +[Toast] 显示消息: 登录成功, 类型: ToastType.SUCCESS, 时长: 5000ms +[Toast] 主窗口: +[Toast] 位置: x=3099, y=20, 屏幕: 3440x1440 +``` + +```bash +/speckit.implement 客户端数据完全没有同步到服务端 +服务的有收到同步请求 +INFO: 127.0.0.1:57552 - "POST /api/v1/sync HTTP/1.1" 200 OK +但数据库中没有任何数据 +``` + +```bash +/speckit.implement ipass-client 客户端出现以下日志： +QMainWindowLayout::addItem: Please use the public QMainWindow API instead + +/speckit.implement 同步后，在表 sync_log 中没有数据 +``` + +```bash +# 010-category-encryption-feishu-notify +/speckit.specify +1. categories 同样需要使用数字证书加密保存 +2. 当成功登陆后，使用飞书群机器人向ipass群发消息，以下是相关配置和要求： +Webhook地址： https://open.feishu.cn/open-apis/bot/v2/hook/24e49f65-80d3-4f58-8fb3-d9ae0013665d +签名校验密钥： xwXYWz6w6Ze9O61ygB4Tne +消息内容：[yyyy-MM-dd HH:MM:SS]xxx登陆。 + +/speckit.plan +/speckit.tasks +/speckit.implement +``` + +```bash +/speckit.specify +1. 移除'界面右上角显示浮动消息'的功能 +2. 统一在窗口的底部增加消息栏，全部消息和提示在消息栏显示，减少弹出窗口和悬浮消息的使用 +3. 在登陆界面显示LOGO +4. 界面宽度缩小后，搜索输入框和分类标题重叠了，修改限制 +5. 使用 ipass-server-cli init 进行初始化的时候，执行 alembic 的迁移脚本 + +/speckit.plan +/speckit.tasks +/speckit.implement +``` + +```bash +/speckit.implement +管理分类窗口中显示的分类名称、描述是乱码 +提示：刷新分类筛选器失败: name 字段解密失败: 解密失败: argument 'nonce': Cannot convert "" instance to a buffer. Did you mean to pass a bytestring instead? +``` + +```bash +/speckit.specify 根据上述分析报告,执行后续行动,立即实施方案 A：创建完整的 common.logging 统一日志模块（**注意：不是ipass.common.logging**）,在整个系统中应用,移除/废弃 server.core.logging.移除 ipass.common.logging . + +/speckit.plan +/speckit.tasks +/speckit.implement +``` + +```bash +/speckit.specify 以现有 trunk 分支为基础，创建功能分支，实现以下功能： +1. 服务端 password_entries 表设计不合理，密码数据不应该和某一个设备绑定。删除设备不要删除分类数据和密码数据。 +2. 添加密码界面，下拉选择的分类中没有看到已经添加的分类，还是显示的模拟分类数据。 +3. 添加密码界面，新添加的分类应该要能在分类管理中看到。 +4. 在密码列表页双击后，点击编辑按钮，在分类中应该显示下拉框。 +5. 清理代码中的直接 print 输出，统一使用日志进行记录。 +6. 按照 @docs/specification.md 中的要求，实现**功能 2: 服务端日志查看**、**功能 14: 日志查看（客户端）** + +/speckit.clarify 前面对删除设备的需求描述错误。删除设备不要删除分类数据和密码数据。 + +/speckit.plan +/speckit.tasks +/speckit.implement +``` \ No newline at end of file diff --git a/工程/VSCode.md b/工程/VSCode.md new file mode 100644 index 0000000..bd41793 --- /dev/null +++ b/工程/VSCode.md @@ -0,0 +1,3 @@ +# [VS Code](https://zread.ai/microsoft/vscode) + +- [VSCode Copilot 终极魔改：以智谱 GLM-4.6 为例，一文搞定任意大模型接入](https://www.cnblogs.com/haibing1992/p/19173013) \ No newline at end of file diff --git a/工程/allenai.md b/工程/allenai.md new file mode 100644 index 0000000..13e532a --- /dev/null +++ b/工程/allenai.md @@ -0,0 +1,4 @@ +# [allenai](https://allenai.org/) + +- [OLMo: Open Language Model](https://github.com/allenai/OLMo-core/) +- [olmocr](https://github.com/allenai/olmocr) diff --git a/工程/本体论.md b/工程/本体论.md new file mode 100644 index 0000000..901a8b5 --- /dev/null +++ b/工程/本体论.md @@ -0,0 +1,71 @@ +# 本体论 Ontology + +## 关键字 + +- 面向对象 Object-Oriented +- 实体关系图 Entity-Relationship Diagram +- 知识图谱 Knowledge Graph +- 本体 Ontology +- 自动化本体学习 +- 可微分推理 + +## 参考 + +- [Harness Engineering 的全新内部工程方法论](https://www.infoq.cn/article/MCUXGhyIRqPLkFhljY9v) +- [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) +- [Skills：从编程工具的配角到Agent研发的核心](https://mp.weixin.qq.com/s/OmA2xcmpXNITxbR5bTsT6w) +- [全面解析：本体论驱动的数据智能决策体系、应用场景与经典案例](https://www.sohu.com/a/982367249_453160) + - 构建AI可理解的业务知识框架，驱动新一代数据智能决策体系 + - 本体论的核心优势在于，它提供了一个超越特定技术栈、特定数据库的通用语义层，能够统一组织内的概念认知，实现数据在更高层面的互操作性和可推理性，是构建真正智能决策系统的基石。 + - 本体论的核心要素 + - 对象类型（Object Type） + - 本体论为知识图谱提供严谨的语义基础和推理能力，使其从单纯的数据关联走向智能推理。 + - Palantir Foundry的“对象”（Objects）概念既是本体论定义的“对象类型”，也是知识图谱中的“实体” + - 本体论定义了领域知识的Schema层（概念框架、属性、关系类型、公理），是知识的骨架，关注知识的定义和推理规则。 + - 知识图谱是基于本体Schema构建的Data层（实例数据），是知识的血肉，由海量事实（实体-关系-实体三元组）构成。它关注具体知识的组织和关联。 + - 属性（Properties） + - 关系（Links） + - 公理（Axioms） + - 本体论（Ontology） + 大语言模型（LLM） + 多智能体（Multi-Agent） + - 奎因提出 本体论承诺（ontological commitment） + - 一个知识系统若能通过清晰的概念定义、属性约束和关系规则实现内部一致性与自洽，即便不追求“绝对真理”，也具备有效的本体论基础 + - 概念形式化（Conceptual Formalization） + - 关系显式化（Explicit Relation Definition） + - 规则与推理机制（Rules and Inference Mechanisms） + - 本体论超越传统数据模型的关键在于引入了“公理”（Axioms）与“推理规则” +- 单一数据库的局限 + - 关系数据库（如PostgreSQL）：擅长结构化数据存储与事务一致性，但处理复杂关系推理（多跳查询）效率低下，缺乏原生公理执行能力。 + - 图数据库（如Neo4j）：擅长关系存储与基于图的推理（路径查询），但对复杂属性管理和事务一致性支持不如关系数据库，处理时序数据效率不高。 + - 时序数据库（如TDengine）：擅长高并发写入、高吞吐量的时序数据（如传感器数据、日志），但缺乏复杂的关联查询和推理能力。 + - 向量数据库（如Milvus）：擅长语义检索、相似度匹配，但难以管理结构化信息和复杂的业务逻辑。 +- [基于本体论与大模型的新一代智能应用开发体系](https://zhuanlan.zhihu.com/p/1953779450626962627) + - 本体的尽管本体系具有巨大潜力，但仍面临诸多挑战： + - 本体构建成本：高质量本体的设计需要领域专家深度参与，初期投入较大。目前行业中有部分从数据库ER图、应用设计图UML自动生成对应本体Ontology的技术探索可供参考。 + - 动态演化：业务规则频繁变化，需建立本体版本管理和动态更新机制。 + - 性能开销：实时推理可能引入延迟，需优化推理算法和缓存策略。 + - 安全与权限：MCP接口需严格的安全控制，防止未授权调用。 + - 未来，随着 知识图谱、自动化本体学习、可微分推理 等技术的发展，本体系将更加智能化和自动化。我们预见，**本体将成为企业数字资产的核心组成部分，而大模型将成为连接知识与行动的智能代理。** + - 软件开发将从“编写代码”转向“构建知识”和“设计智能”，开启人机协同的新纪元。 +- [AI+软件工程的加速演进：2028年会呈现怎样的实景？](https://www.sohu.com/a/989732747_453160) +- [Palantir Foundry](https://www.palantir.com/platforms/foundry/) + - [Foundry Platform SDK](https://github.com/palantir/foundry-platform-python) + - [Ontology SDK](https://www.palantir.com/docs/foundry/ontology-sdk/overview/) + - [console](https://www.palantir.com/docs/foundry/developer-console/overview) + - [toolchain](https://www.palantir.com/docs/foundry/dev-toolchain/overview) + - 企业级实用本体论及构建指南系列 + - [Palantir 数据建模的哲学与实践](https://blog.csdn.net/xianggll/article/details/156512850) + - [Palantir Foundry如何将组织数据映射到本体概念及关键设计考量](https://blog.csdn.net/xianggll/article/details/156540178) + - [Palantir Foundry中的对象、事件与时间序列](https://blog.csdn.net/xianggll/article/details/156560480) + - [通过Foundry Actions激活数据生态系统](https://blog.csdn.net/xianggll/article/details/156647844) +- [UINO 优锘科技](https://www.uino.com/) + - 本体智能 + - [（一）为什么你的AI项目，总是"差点意思"？](https://zhuanlan.zhihu.com/p/81787560659) + - [（二）传统架构与AI原生需求之间的四大“鸿沟”](https://zhuanlan.zhihu.com/p/1964639741694682418) + - 智能问数从朴素到科学 + - [一：为什么智能问数止步 Demo？](https://mp.weixin.qq.com/s/GyjPpQy1R3StX82kRlnPGQ) + - [二：文档 RAG 问数的天花板](https://mp.weixin.qq.com/s/SMjKeyipSmu3znlEwkyTLg) + - [三：Text-to-SQL 的准确性困境](https://mp.weixin.qq.com/s/nhzE86G_asPKLDz-G_VIww) + - [四：指标语义化的边界](https://mp.weixin.qq.com/s/MMtESifieEJVpOE4c6Z7uw) +- [Palantir本体论深度解读：企业AI的语义操作系统从数据孤岛到智能决策的革命性跨越](https://zhuanlan.zhihu.com/p/1968630511132991727) +- [Ontology Building – 打造组织的运营层与数字孪生](https://blog.csdn.net/xianggll/article/details/158568659) +- [Palantir的本体论实践：一套方法论与四个应用场景](https://www.eet-china.com/mp/a465449.html)