{"updated":"2026-10-10","count":45,"note":"Compiled from official docs and public discussions; not reproduced in our environment yet.","problems":[{"slug":"mcp-server-not-connecting","type":"error","scenario":"connect-tools-to-agents","needs":["DEV-07"],"software":["modelcontextprotocol-inspector","modelcontextprotocol-servers","typescript-sdk","python-sdk"],"sources":[{"label":"MCP 官方调试指南 / MCP debugging guide","url":"https://modelcontextprotocol.io/docs/tools/debugging"},{"label":"MCP Inspector","url":"https://github.com/modelcontextprotocol/inspector"}],"verified":"2026-10-10","zh":{"title":"MCP 服务器连不上：Connection closed / MCP error -32000","summary":"客户端启动 MCP 服务器后立刻断开，最常见的原因是启动命令本身失败，或服务器往标准输出里打印了日志。","symptoms":["客户端显示 “Connection closed”、“MCP error -32000” 或服务器状态为 failed","工具列表为空，日志里只有一行启动命令"],"causes":["启动命令在客户端的环境里找不到（图形界面应用的 PATH 和终端不同，`npx`、`uvx` 找不到）","stdio 传输模式下，服务器把日志写到了 stdout，破坏了 JSON-RPC 消息","缺少必需的环境变量（API key 等），服务器启动即退出","Windows 上直接调用 `npx` 失败，需要通过 `cmd /c` 启动"],"steps":["先在终端里手动运行配置里的完整命令，确认它能启动且不报错","用 MCP Inspector 单独测试服务器：`npx @modelcontextprotocol/inspector <你的启动命令>`，看能否列出工具","在配置里把 `command` 写成绝对路径（如 `which npx` 的结果），并在 `env` 里显式传入需要的变量","检查服务器代码：stdio 模式下日志只能写到 stderr","查看客户端自己的 MCP 日志（各客户端位置不同，见其文档），根据第一条报错定位"],"notes":["不要为了排错把密钥贴到公开 issue 里"]},"en":{"title":"MCP server won’t connect: “Connection closed” / MCP error -32000","summary":"When a client drops an MCP server right after launching it, the launch command usually failed or the server printed logs to stdout.","symptoms":["The client shows “Connection closed”, “MCP error -32000” or a failed server status","The tool list is empty and the log only shows the launch command"],"causes":["The command is not found in the client’s environment (GUI apps have a different PATH from your terminal, so `npx` or `uvx` is missing)","In stdio mode the server writes logs to stdout, corrupting the JSON-RPC stream","A required environment variable (API key etc.) is missing and the server exits at start-up","On Windows, calling `npx` directly fails and must be wrapped in `cmd /c`"],"steps":["Run the exact command from your config in a terminal and make sure it starts without errors","Test the server on its own with MCP Inspector: `npx @modelcontextprotocol/inspector <your command>` and check that tools are listed","Use an absolute path for `command` (e.g. the output of `which npx`) and pass required variables explicitly in `env`","In the server code, write logs to stderr only when using stdio","Read the client’s own MCP log (location differs per client; see its docs) and start from the first error"],"notes":["Never paste secrets into public issues while debugging"]},"pages":{"en":"https://aimap.page/en/problems/mcp-server-not-connecting/","zh-hans":"https://aimap.page/zh-hans/problems/mcp-server-not-connecting/"}},{"slug":"mcp-too-many-tools-context","type":"howto","scenario":"connect-tools-to-agents","needs":["DEV-07","AGT-05"],"software":["metamcp","mcp-context-forge","mcp-gateway","modelcontextprotocol-registry"],"sources":[{"label":"MCP 官方调试指南 / MCP debugging guide","url":"https://modelcontextprotocol.io/docs/tools/debugging"}],"verified":"2026-10-10","zh":{"title":"MCP 工具太多，工具定义占满上下文怎么办","summary":"每个已连接的 MCP 服务器都会把全部工具的名称、描述和参数 schema 放进上下文。服务器接得越多，留给任务的上下文越少，模型也更容易选错工具。","symptoms":["对话一开始上下文就用掉一大块","agent 经常调用不相关的工具，或者回答变慢、变贵"],"causes":["全局启用了很多只偶尔用到的服务器","单个服务器暴露几十个工具，描述冗长"],"steps":["按项目配置 MCP：只在需要的项目里启用对应服务器，不要全部放进全局配置","使用客户端提供的工具允许列表或禁用开关，只保留当前任务要用的工具","用 MCP 网关或聚合器（如 MetaMCP、ContextForge）把多个服务器聚合起来，按场景只暴露一部分工具","简单操作（读文件、跑测试、查 git）优先让 agent 直接用命令行，不必再接一个 MCP","在本站软件库里按类别对比同类服务器，选工具少而精的那个"],"notes":[]},"en":{"title":"Too many MCP tools filling the context window","summary":"Every connected MCP server puts the name, description and parameter schema of all its tools into the context. The more servers you connect, the less room is left for the task and the more often the model picks the wrong tool.","symptoms":["A large share of the context is used before you type anything","The agent calls unrelated tools, or responses get slower and more expensive"],"causes":["Many rarely used servers are enabled globally","A single server exposes dozens of tools with long descriptions"],"steps":["Configure MCP per project and enable servers only where they are needed instead of globally","Use the client’s tool allow-list or disable switches to keep only the tools the task needs","Put servers behind an MCP gateway or aggregator (e.g. MetaMCP, ContextForge) and expose only a subset per use case","For simple actions (reading files, running tests, git) let the agent use the command line directly instead of another MCP server","Compare servers of the same kind in our software library and prefer the one with fewer, focused tools"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/mcp-too-many-tools-context/","zh-hans":"https://aimap.page/zh-hans/problems/mcp-too-many-tools-context/"}},{"slug":"mcp-remote-oauth-fails","type":"error","scenario":"connect-tools-to-agents","needs":["AGT-04"],"software":["modelcontextprotocol-inspector","github-mcp-server"],"sources":[{"label":"MCP 授权规范 / MCP authorization spec","url":"https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization"},{"label":"MCP Inspector","url":"https://github.com/modelcontextprotocol/inspector"}],"verified":"2026-10-10","zh":{"title":"远程 MCP 服务器 OAuth 授权失败","summary":"远程（HTTP）MCP 服务器通常用 OAuth 授权。授权失败多半是客户端不支持对应流程、回调地址不匹配，或令牌过期没有刷新。","symptoms":["浏览器授权页打不开或报 redirect_uri 错误","授权成功后一段时间工具调用返回 401"],"causes":["客户端版本不支持远程 MCP 的 OAuth 或动态客户端注册（DCR）","在服务方后台登记的回调地址和客户端实际使用的不一致","令牌过期，客户端没有自动刷新","请求的权限范围（scope）不够"],"steps":["确认客户端文档写明支持远程 MCP 授权；不支持时改用服务方提供的个人访问令牌（PAT）方式","用 MCP Inspector 连接同一个远程地址，单独走一遍授权流程，区分是服务端还是客户端的问题","核对服务方后台登记的回调地址","在客户端里清除该服务器的授权状态后重新登录","只申请任务需要的最小权限范围"],"notes":["令牌等同密码，不要写进仓库"]},"en":{"title":"Remote MCP server OAuth fails","summary":"Remote (HTTP) MCP servers usually use OAuth. Failures mostly come from a client that does not support the flow, a redirect URI mismatch, or an expired token that was not refreshed.","symptoms":["The authorization page fails to open or shows a redirect_uri error","Tool calls return 401 some time after a successful login"],"causes":["The client version does not support OAuth or dynamic client registration (DCR) for remote MCP","The redirect URI registered with the provider differs from the one the client uses","The token expired and the client did not refresh it","The requested scopes are insufficient"],"steps":["Check that the client’s docs say it supports remote MCP authorization; if not, use the provider’s personal access token (PAT) option","Connect MCP Inspector to the same remote URL and run the flow on its own to tell server problems from client problems","Verify the redirect URI registered with the provider","Clear the server’s stored authorization in the client and sign in again","Request only the minimum scopes the task needs"],"notes":["Treat tokens like passwords and keep them out of repositories"]},"pages":{"en":"https://aimap.page/en/problems/mcp-remote-oauth-fails/","zh-hans":"https://aimap.page/zh-hans/problems/mcp-remote-oauth-fails/"}},{"slug":"how-to-write-agents-md","type":"howto","scenario":"share-rules-and-skills","needs":["DEV-11"],"software":["agents-md","codex","claude-code"],"sources":[{"label":"AGENTS.md","url":"https://agents.md/"},{"label":"Claude Code memory (CLAUDE.md)","url":"https://code.claude.com/docs/en/memory"}],"verified":"2026-10-10","zh":{"title":"AGENTS.md 怎么写","summary":"AGENTS.md 是放在仓库里给编程 agent 看的说明文件，作用类似给新同事的 README：怎么构建、怎么测试、代码规范和提交要求。","symptoms":["agent 每次都要重新摸索怎么跑测试","不同 agent 生成的代码风格不一致"],"causes":["仓库里没有给 agent 的固定说明，或者说明分散在多个工具各自的文件里"],"steps":["在仓库根目录新建 `AGENTS.md`，写清楚安装依赖、构建、运行测试和 lint 的确切命令","写代码规范、目录结构要点、不允许做的事（例如不要改生成文件、不要直接推主分支）","大型仓库可以在子目录再放 `AGENTS.md`，就近覆盖该目录的规则","保持简短具体，写命令和规则，不写空泛的口号；规则变了随代码一起改","Claude Code 读取的是 `CLAUDE.md`，可以在其中引用或链接到 `AGENTS.md`，避免维护两份"],"notes":[]},"en":{"title":"How to write AGENTS.md","summary":"AGENTS.md is a file in your repository written for coding agents, like a README for a new colleague: how to build, how to test, code style and commit rules.","symptoms":["The agent rediscovers how to run tests every time","Different agents produce code in different styles"],"causes":["The repository has no stable instructions for agents, or they are scattered across tool-specific files"],"steps":["Create `AGENTS.md` at the repository root with the exact commands to install dependencies, build, run tests and lint","Add code-style rules, key points about the directory layout and things not to do (e.g. do not edit generated files, do not push to main)","In large repositories, add `AGENTS.md` files in subdirectories to override rules locally","Keep it short and concrete: commands and rules, not slogans; update it together with the code","Claude Code reads `CLAUDE.md`; reference or link `AGENTS.md` from it so you maintain one copy"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/how-to-write-agents-md/","zh-hans":"https://aimap.page/zh-hans/problems/how-to-write-agents-md/"}},{"slug":"share-rules-across-agents","type":"howto","scenario":"share-rules-and-skills","needs":["AGT-02","DEV-11"],"software":["agents-md","claude-code","cursor","gemini-cli","codex"],"sources":[{"label":"AGENTS.md","url":"https://agents.md/"},{"label":"Claude Code memory","url":"https://code.claude.com/docs/en/memory"},{"label":"Gemini CLI","url":"https://github.com/google-gemini/gemini-cli"}],"verified":"2026-10-10","zh":{"title":"在 Claude Code、Codex、Cursor、Gemini CLI 之间共用一套规则","summary":"各家 agent 读取的规则文件名不同。做法是保留一份主文件（推荐 AGENTS.md），其他工具通过引用、软链接或配置指向它。","symptoms":["同样的规则要在 CLAUDE.md、.cursor/rules、GEMINI.md 里各维护一份，经常不同步"],"causes":["各工具默认读取的文件名和位置不同"],"steps":["把规则写进仓库根目录的 `AGENTS.md`，作为唯一来源","Claude Code：在 `CLAUDE.md` 里引用 `AGENTS.md`，或建立软链接 `ln -s AGENTS.md CLAUDE.md`","Gemini CLI：可在其设置里修改上下文文件名，让它读取 `AGENTS.md`（以官方文档当前说明为准）","Cursor：在项目规则里引用同一份内容；新版本是否直接读取 AGENTS.md 以官方文档为准","每次改规则后，在各工具里各跑一次简单任务确认已生效"],"notes":["软链接在 Windows 上需要额外权限，可改用引用方式"]},"en":{"title":"Share one set of rules across Claude Code, Codex, Cursor and Gemini CLI","summary":"Each agent reads a different rules file. Keep one main file (AGENTS.md is the usual choice) and point the other tools at it by reference, symlink or configuration.","symptoms":["The same rules are maintained separately in CLAUDE.md, .cursor/rules and GEMINI.md and drift apart"],"causes":["Each tool reads a different default file name and location"],"steps":["Put the rules in `AGENTS.md` at the repository root as the single source","Claude Code: reference `AGENTS.md` from `CLAUDE.md`, or create a symlink `ln -s AGENTS.md CLAUDE.md`","Gemini CLI: its settings let you change the context file name so it reads `AGENTS.md` (check the current official docs)","Cursor: reference the same content from project rules; whether newer versions read AGENTS.md directly is documented officially","After changing rules, run a small task in each tool to confirm they are picked up"],"notes":["Symlinks need extra permissions on Windows; use references instead"]},"pages":{"en":"https://aimap.page/en/problems/share-rules-across-agents/","zh-hans":"https://aimap.page/zh-hans/problems/share-rules-across-agents/"}},{"slug":"agent-skills-skill-md","type":"howto","scenario":"share-rules-and-skills","needs":["AGT-02"],"software":["anthropics-skills","mattpocock-skills","claude-code"],"sources":[{"label":"anthropics/skills","url":"https://github.com/anthropics/skills"}],"verified":"2026-10-10","zh":{"title":"Agent Skills（SKILL.md）是什么，怎么复用","summary":"技能（Skill）是一个文件夹，核心是一份带 YAML 头信息（名称、描述）的 SKILL.md，可附带脚本和参考资料。agent 按描述判断何时加载，比把所有说明塞进规则文件更省上下文。","symptoms":["规则文件越写越长，大部分内容和当前任务无关"],"causes":["所有说明一次性加载，没有按需加载机制"],"steps":["把一类可复用的操作（例如生成发布说明、处理 PDF）整理成一个技能文件夹，里面放 `SKILL.md`","在 SKILL.md 头部写清 `name` 和 `description`，描述要说明“什么时候用”","把长参考资料和脚本放在同一文件夹，由 SKILL.md 按需引用","参考官方和社区的技能仓库（见下方软件）作为模板","其他 agent 对技能格式的支持程度不同，使用前查看各自文档"],"notes":[]},"en":{"title":"What Agent Skills (SKILL.md) are and how to reuse them","summary":"A skill is a folder whose core is a SKILL.md with YAML front matter (name, description), optionally with scripts and references. The agent loads it when the description matches the task, which saves context compared with stuffing everything into a rules file.","symptoms":["Rules files keep growing and most of the content is irrelevant to the current task"],"causes":["All instructions are loaded at once; there is no on-demand loading"],"steps":["Package a reusable procedure (e.g. writing release notes, handling PDFs) as a skill folder containing `SKILL.md`","Give SKILL.md a clear `name` and a `description` that says when to use it","Keep long references and scripts in the same folder and point to them from SKILL.md","Use the official and community skill repositories (see software below) as templates","Support for the skill format differs between agents; check each one’s docs first"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/agent-skills-skill-md/","zh-hans":"https://aimap.page/zh-hans/problems/agent-skills-skill-md/"}},{"slug":"claude-code-with-other-models","type":"howto","scenario":"switch-models","needs":["AGT-03","OSS-06"],"software":["claude-code","claude-code-router","litellm","cc-switch"],"sources":[{"label":"Claude Code LLM gateway","url":"https://code.claude.com/docs/en/llm-gateway"},{"label":"Claude Code settings","url":"https://code.claude.com/docs/en/settings"},{"label":"claude-code-router","url":"https://github.com/musistudio/claude-code-router"}],"verified":"2026-10-10","zh":{"title":"让 Claude Code 使用其他模型（国产模型、自建网关）","summary":"Claude Code 支持通过环境变量把请求发到兼容 Anthropic API 的地址。不少模型厂商提供了 Anthropic 兼容接口，也可以经由 LiteLLM 等网关或 claude-code-router 转换。","symptoms":["想用公司网关或其他厂商的模型跑 Claude Code"],"causes":["默认请求直接发往 Anthropic 官方"],"steps":["确认目标厂商官方文档提供 Anthropic 兼容接口，并拿到它给出的 base URL 和 key","设置环境变量 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`（或写进 Claude Code 的 settings.json 的 `env`），按厂商文档指定模型名","厂商只提供 OpenAI 格式时，用 LiteLLM 或 claude-code-router 做协议转换","用 cc-switch 之类的工具在多套配置之间切换","先用小任务测试工具调用和长上下文是否正常；不同模型的工具调用质量差别很大"],"notes":["只使用官方或合规的接口，不使用来路不明的中转和共享账号"]},"en":{"title":"Use Claude Code with other models (Chinese models, your own gateway)","summary":"Claude Code can send requests to any Anthropic-compatible endpoint set via environment variables. Many model vendors offer Anthropic-compatible APIs, and gateways such as LiteLLM or claude-code-router can translate formats.","symptoms":["You want Claude Code to use a company gateway or another vendor’s model"],"causes":["By default requests go straight to Anthropic"],"steps":["Check that the vendor’s official docs offer an Anthropic-compatible API and get the base URL and key they provide","Set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` (or put them under `env` in Claude Code’s settings.json) and set the model name as the vendor documents","If the vendor only offers the OpenAI format, translate with LiteLLM or claude-code-router","Use a tool such as cc-switch to switch between configurations","Test tool calling and long context on small tasks first; tool-calling quality varies a lot between models"],"notes":["Use only official or compliant endpoints, never unknown relays or shared accounts"]},"pages":{"en":"https://aimap.page/en/problems/claude-code-with-other-models/","zh-hans":"https://aimap.page/zh-hans/problems/claude-code-with-other-models/"}},{"slug":"codex-cli-local-or-custom-models","type":"howto","scenario":"switch-models","needs":["AGT-03"],"software":["codex","ollama","litellm"],"sources":[{"label":"Codex configuration","url":"https://github.com/openai/codex/blob/main/docs/config.md"},{"label":"Ollama FAQ","url":"https://docs.ollama.com/faq"}],"verified":"2026-10-10","zh":{"title":"让 Codex CLI 用本地模型或自定义模型服务","summary":"Codex CLI 的配置文件支持自定义模型提供方（model provider），可以指向 OpenAI 兼容的地址，包括本地 Ollama。","symptoms":["想在离线或内网环境用 Codex CLI","想接入公司内部的模型服务"],"causes":["默认只配置了 OpenAI 官方提供方"],"steps":["打开 Codex 的配置文件（`~/.codex/config.toml`），按官方配置文档添加一个 model provider，填入 base URL 和环境变量名","本地模型：先用 Ollama 拉取模型并确认 `http://localhost:11434` 可访问，再把提供方指向它","在配置里把默认模型改成该提供方下的模型名，或在命令行临时指定","本地小模型的工具调用能力有限，先用简单任务验证"],"notes":[]},"en":{"title":"Use Codex CLI with local or custom model providers","summary":"Codex CLI’s config file supports custom model providers that point at any OpenAI-compatible endpoint, including a local Ollama.","symptoms":["You want to use Codex CLI offline or on an internal network","You want to use your company’s model service"],"causes":["Only the official OpenAI provider is configured by default"],"steps":["Open Codex’s config file (`~/.codex/config.toml`) and add a model provider with its base URL and environment variable name, following the official config docs","Local models: pull a model with Ollama, confirm `http://localhost:11434` responds, then point the provider at it","Set the default model to one served by that provider, or pass it on the command line","Small local models have limited tool-calling ability; validate with simple tasks first"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/codex-cli-local-or-custom-models/","zh-hans":"https://aimap.page/zh-hans/problems/codex-cli-local-or-custom-models/"}},{"slug":"what-model-fits-my-vram","type":"choice","scenario":"run-models-locally","needs":["DEV-08","IND-03"],"software":["ollama","llama-cpp","lm-studio","mlx-lm"],"sources":[{"label":"Ollama FAQ","url":"https://docs.ollama.com/faq"},{"label":"llama.cpp server","url":"https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md"}],"verified":"2026-10-10","zh":{"title":"我的显存/内存能跑多大的模型","summary":"粗略估算：模型权重占用 ≈ 参数量 × 每个参数的位数 ÷ 8，再加上上下文（KV cache）和运行时开销。4 位量化时，每 10 亿参数大约需要 0.5–0.7 GB。","symptoms":["模型下载后加载失败、速度极慢，或系统开始大量使用内存交换"],"causes":["模型权重加上下文超过了可用显存（Apple 芯片为统一内存）","上下文开得太长，KV cache 占用随长度增长"],"steps":["先按 4 位量化估算：7–8B 约 5 GB，14B 约 9 GB，32B 约 20 GB，70B 约 40 GB 以上（只是量级，具体看模型和量化方式）","给上下文和系统留出余量：显存 8 GB 适合 7–8B，16 GB 可以考虑 14B，24 GB 可以试 32B 的 4 位量化","Mac 用户可用统一内存的大部分，但不能全部；MLX（mlx-lm）和 llama.cpp 都支持 Apple 芯片","上下文长度按需设置，不要直接开到模型上限","在本站免费模型板块查看开放权重模型的参数量和许可证"],"notes":["以上是经验估算，不是本站实测结果"]},"en":{"title":"What model size can my VRAM / RAM run?","summary":"Rule of thumb: weight memory ≈ parameters × bits per parameter ÷ 8, plus context (KV cache) and runtime overhead. At 4-bit quantisation that is roughly 0.5–0.7 GB per billion parameters.","symptoms":["The model fails to load, runs extremely slowly, or the system starts swapping"],"causes":["Weights plus context exceed available VRAM (unified memory on Apple silicon)","The context is set too long; KV cache grows with length"],"steps":["Estimate at 4-bit: 7–8B ≈ 5 GB, 14B ≈ 9 GB, 32B ≈ 20 GB, 70B ≈ 40 GB or more (orders of magnitude only; depends on model and quantisation)","Leave headroom for context and the OS: 8 GB VRAM suits 7–8B, 16 GB can try 14B, 24 GB can try a 4-bit 32B","On a Mac you can use most, but not all, unified memory; MLX (mlx-lm) and llama.cpp both support Apple silicon","Set context length to what you need instead of the model’s maximum","See parameter counts and licences of open-weight models in our Free models section"],"notes":["These are rules of thumb, not our own measurements"]},"pages":{"en":"https://aimap.page/en/problems/what-model-fits-my-vram/","zh-hans":"https://aimap.page/zh-hans/problems/what-model-fits-my-vram/"}},{"slug":"ollama-context-length-truncated","type":"error","scenario":"run-models-locally","needs":["DEV-08"],"software":["ollama","open-webui"],"sources":[{"label":"Ollama FAQ","url":"https://docs.ollama.com/faq"}],"verified":"2026-10-10","zh":{"title":"Ollama 长文档被截断、模型“忘记”前文","summary":"Ollama 默认的上下文长度比很多模型支持的上限小得多（默认值随版本变化）。输入超过上下文长度时，前面的内容会被丢掉。","symptoms":["把长文档发给本地模型，回答只涉及最后一部分","agent 在多轮对话后忘记早先的指令"],"causes":["上下文长度（num_ctx）仍是默认值"],"steps":["临时调整：在 `ollama run` 会话里输入 `/set parameter num_ctx 16384`","全局调整：启动服务前设置环境变量 `OLLAMA_CONTEXT_LENGTH`（较新版本支持，见官方 FAQ）","通过 API 调用时，在请求的 `options` 里传 `num_ctx`","也可以写一个 Modelfile，加入 `PARAMETER num_ctx 16384` 后 `ollama create` 一个新模型","上下文越大占用显存越多，按硬件量力设置"],"notes":[]},"en":{"title":"Ollama truncates long documents and the model “forgets” earlier text","summary":"Ollama’s default context length is much smaller than many models support (the default changes between versions). When input exceeds it, earlier content is dropped.","symptoms":["Answers about a long document only cover its last part","An agent forgets earlier instructions after several turns"],"causes":["The context length (num_ctx) is still the default"],"steps":["Temporarily: in an `ollama run` session type `/set parameter num_ctx 16384`","Globally: set the `OLLAMA_CONTEXT_LENGTH` environment variable before starting the server (newer versions; see the official FAQ)","Via the API: pass `num_ctx` in the request `options`","Or write a Modelfile with `PARAMETER num_ctx 16384` and `ollama create` a new model","A larger context uses more memory; size it to your hardware"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/ollama-context-length-truncated/","zh-hans":"https://aimap.page/zh-hans/problems/ollama-context-length-truncated/"}},{"slug":"llama-cpp-chat-template-tool-calls","type":"error","scenario":"run-models-locally","needs":["DEV-08"],"software":["llama-cpp","lm-studio"],"sources":[{"label":"llama.cpp server README","url":"https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md"}],"verified":"2026-10-10","zh":{"title":"llama.cpp 输出乱码、角色混乱或不调用工具","summary":"对话模板（chat template）决定了消息怎样拼成模型训练时见过的格式。模板不对时，模型会输出奇怪的标记、自问自答，或者不按格式调用工具。","symptoms":["回答里出现 `<|im_start|>` 之类的特殊标记","模型从不调用工具，或工具调用格式错误"],"causes":["服务端没有使用模型自带的模板","GGUF 文件里的模板过旧或缺失"],"steps":["用 `llama-server` 启动时加上 `--jinja`，使用 GGUF 内嵌的 Jinja 模板（工具调用通常依赖它）","模板有问题时用 `--chat-template-file` 指定从模型官方仓库取得的模板文件","换用模型发布方或可信量化者提供的较新 GGUF 文件","LM Studio 等图形客户端可在模型设置里检查和替换提示模板"],"notes":[]},"en":{"title":"llama.cpp prints garbage, mixes up roles or never calls tools","summary":"The chat template turns messages into the format the model was trained on. With the wrong template the model emits odd tokens, talks to itself or fails to call tools properly.","symptoms":["Special tokens like `<|im_start|>` appear in answers","The model never calls tools, or tool calls are malformed"],"causes":["The server is not using the model’s own template","The template in the GGUF file is outdated or missing"],"steps":["Start `llama-server` with `--jinja` to use the Jinja template embedded in the GGUF (tool calling usually depends on it)","If the template is broken, pass `--chat-template-file` with the template from the model’s official repository","Use a newer GGUF from the model publisher or a trusted quantiser","GUI clients such as LM Studio let you inspect and replace the prompt template in model settings"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/llama-cpp-chat-template-tool-calls/","zh-hans":"https://aimap.page/zh-hans/problems/llama-cpp-chat-template-tool-calls/"}},{"slug":"vllm-cuda-out-of-memory","type":"error","scenario":"run-models-locally","needs":["DEV-08"],"software":["vllm","sglang"],"sources":[{"label":"vLLM","url":"https://github.com/vllm-project/vllm"}],"verified":"2026-10-10","zh":{"title":"vLLM 启动时报 CUDA out of memory","summary":"vLLM 启动时会按设定比例预先占用显存，并为最大上下文长度预留 KV cache。模型加上下文放不下时会直接报显存不足。","symptoms":["启动日志出现 `CUDA out of memory` 或提示 KV cache 空间不足"],"causes":["最大上下文长度默认取模型上限，KV cache 需求过大","显存被其他进程占用","模型未量化，权重本身就超出单卡显存"],"steps":["用 `--max-model-len` 把最大上下文调到实际需要的长度","用 `--gpu-memory-utilization` 调整预占比例（例如在显卡被其他进程共用时调低）","多卡时用 `--tensor-parallel-size` 把模型切分到多张卡","改用量化版本的模型（如 AWQ、GPTQ、FP8，取决于硬件支持）","用 `nvidia-smi` 确认没有其他进程占用显存"],"notes":[]},"en":{"title":"vLLM fails at start-up with CUDA out of memory","summary":"At start-up vLLM pre-allocates a share of GPU memory and reserves KV cache for the maximum context length. If the model plus context does not fit, it fails immediately.","symptoms":["The log shows `CUDA out of memory` or says there is not enough KV cache space"],"causes":["Max context length defaults to the model’s maximum, so the KV cache requirement is too large","Other processes are using GPU memory","The model is unquantised and the weights alone exceed one GPU"],"steps":["Lower the maximum context with `--max-model-len` to what you actually need","Adjust pre-allocation with `--gpu-memory-utilization` (lower it if the GPU is shared)","With several GPUs, split the model with `--tensor-parallel-size`","Use a quantised model (AWQ, GPTQ, FP8, depending on hardware support)","Check with `nvidia-smi` that no other process holds GPU memory"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/vllm-cuda-out-of-memory/","zh-hans":"https://aimap.page/zh-hans/problems/vllm-cuda-out-of-memory/"}},{"slug":"prevent-agent-destructive-actions","type":"howto","scenario":"safe-agent-execution","needs":["DEV-06"],"software":["anthropic-ai-sandbox-runtime","e2b","docker-desktop","bubblewrap","git"],"sources":[{"label":"Dev Containers","url":"https://containers.dev/"},{"label":"sandbox-runtime","url":"https://github.com/anthropic-experimental/sandbox-runtime"},{"label":"E2B docs","url":"https://e2b.dev/docs"}],"verified":"2026-10-10","zh":{"title":"防止 agent 删除文件、执行危险命令","summary":"让 agent 少犯不可逆的错误，靠的是三层：执行环境隔离、权限最小化、操作前有检查点。","symptoms":["agent 执行了 `rm -rf`、`git reset --hard` 或覆盖了未提交的改动"],"causes":["agent 直接在宿主机、以你的用户权限运行","开启了“全部自动批准”","工作区没有提交，无法回退"],"steps":["在容器、devcontainer 或沙箱里运行 agent（本地可用 Docker、bubblewrap、sandbox-runtime；云端可用 E2B 等）","只挂载项目目录，不挂载家目录、SSH 密钥和云凭证；默认关闭或限制网络访问","使用客户端的权限模式和拒绝规则，把删除、推送、改配置之类的命令设为必须人工确认","开工前先提交或建分支/工作树，让每次改动都可回退","定期备份，不把唯一副本交给 agent 处理"],"notes":[]},"en":{"title":"Stop agents from deleting files or running dangerous commands","summary":"Avoiding irreversible agent mistakes takes three layers: an isolated environment, least privilege, and a checkpoint before acting.","symptoms":["The agent ran `rm -rf`, `git reset --hard` or overwrote uncommitted work"],"causes":["The agent runs directly on the host with your user’s permissions","“Auto-approve everything” is on","Work was not committed, so there is nothing to roll back to"],"steps":["Run the agent in a container, devcontainer or sandbox (locally Docker, bubblewrap or sandbox-runtime; in the cloud E2B and similar)","Mount only the project directory, not your home directory, SSH keys or cloud credentials; disable or restrict network access by default","Use the client’s permission modes and deny rules so deletes, pushes and config changes always need human approval","Commit or create a branch/worktree before starting so every change can be undone","Keep backups; never hand the only copy of anything to an agent"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/prevent-agent-destructive-actions/","zh-hans":"https://aimap.page/zh-hans/problems/prevent-agent-destructive-actions/"}},{"slug":"undo-agent-changes-with-git","type":"howto","scenario":"safe-agent-execution","needs":["AGT-07","DEV-06"],"software":["git"],"sources":[{"label":"git worktree","url":"https://git-scm.com/docs/git-worktree"},{"label":"git reflog","url":"https://git-scm.com/docs/git-reflog"}],"verified":"2026-10-10","zh":{"title":"撤回 agent 的改动：git 检查点、worktree 和 reflog","summary":"git 是最可靠的 agent “撤销键”：每个任务一个分支或工作树，频繁提交；误操作后还能用 reflog 找回已提交过的状态。","symptoms":["agent 改坏了代码，想回到几步之前","执行了 `git reset --hard` 后提交“消失”了"],"causes":["改动没有提交，或多个 agent 在同一工作目录里互相覆盖"],"steps":["每个 agent 任务用独立分支，或用 `git worktree add ../task-x -b task-x` 建独立工作树","让 agent 在每个可用的小步骤后提交，便于逐步回退","误用 `reset --hard` 后，运行 `git reflog` 找到之前的提交号，再 `git reset --hard <提交号>` 或新建分支恢复","未提交、未暂存的改动 git 无法找回，所以开工前先提交"],"notes":[]},"en":{"title":"Undo agent changes: git checkpoints, worktrees and reflog","summary":"git is the most reliable undo button for agents: one branch or worktree per task, frequent commits, and reflog to recover committed states after a mistake.","symptoms":["The agent broke the code and you want to go back a few steps","Commits “disappeared” after `git reset --hard`"],"causes":["Changes were not committed, or several agents overwrite each other in one working directory"],"steps":["Give each agent task its own branch, or its own worktree with `git worktree add ../task-x -b task-x`","Have the agent commit after each working step so you can roll back gradually","After a mistaken `reset --hard`, run `git reflog` to find the earlier commit and `git reset --hard <commit>` or create a branch from it","git cannot recover changes that were never committed or staged, so commit before starting"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/undo-agent-changes-with-git/","zh-hans":"https://aimap.page/zh-hans/problems/undo-agent-changes-with-git/"}},{"slug":"agent-secrets-env-leak","type":"howto","scenario":"safe-agent-execution","needs":["DEV-09","AGT-07","ENT-06"],"software":["gitleaks","trufflehog","vault","infisical"],"sources":[{"label":"gitleaks","url":"https://github.com/gitleaks/gitleaks"},{"label":"trufflehog","url":"https://github.com/trufflesecurity/trufflehog"}],"verified":"2026-10-10","zh":{"title":"防止 agent 读取 .env、把密钥提交进仓库","summary":"agent 能读到的文件，内容就可能进入模型上下文、日志甚至提交记录。要从“少暴露、早发现、快轮换”三方面处理。","symptoms":["API key 出现在提交记录或 agent 日志里","收到平台发来的密钥泄露通知"],"causes":["密钥以明文放在项目目录的 `.env` 里，agent 有读取权限","没有提交前扫描"],"steps":["用客户端的拒绝规则禁止读取 `.env`、密钥文件和凭证目录","把密钥放进密钥管理工具（如 Vault、Infisical），运行时注入，不落盘到仓库","加 pre-commit 扫描：例如 `gitleaks git` 或 `gitleaks protect`（命令以所用版本文档为准），CI 里再扫一遍","已经泄露的密钥第一时间在服务商后台作废并重新生成；只删提交记录不够","用 trufflehog 扫描完整历史，确认没有其他遗漏"],"notes":[]},"en":{"title":"Keep agents from reading .env files and committing secrets","summary":"Any file an agent can read may end up in the model context, logs or even commits. Handle it on three fronts: expose less, detect early, rotate fast.","symptoms":["API keys show up in commits or agent logs","A provider notifies you of a leaked key"],"causes":["Secrets live in plain text in the project’s `.env` and the agent can read it","There is no pre-commit scanning"],"steps":["Use the client’s deny rules to block reading `.env`, key files and credential directories","Keep secrets in a secrets manager (e.g. Vault, Infisical) and inject them at run time instead of storing them in the repo","Add pre-commit scanning, e.g. `gitleaks git` or `gitleaks protect` (check your version’s docs), and scan again in CI","Revoke and regenerate leaked keys at the provider immediately; deleting the commit is not enough","Scan the full history with trufflehog to make sure nothing else slipped through"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/agent-secrets-env-leak/","zh-hans":"https://aimap.page/zh-hans/problems/agent-secrets-env-leak/"}},{"slug":"prompt-injection-defense","type":"howto","scenario":"safe-agent-execution","needs":["DEV-09"],"software":["garak","llm-guard","purplellama"],"sources":[{"label":"garak","url":"https://github.com/NVIDIA/garak"},{"label":"LLM Guard","url":"https://github.com/protectai/llm-guard"}],"verified":"2026-10-10","zh":{"title":"agent 读网页、文档时被提示注入怎么防","summary":"提示注入目前没有能彻底解决的办法。实际做法是把外部内容当作不可信数据，限制 agent 读到注入内容后能造成的破坏。","symptoms":["agent 读了某个网页或 issue 后，开始执行与任务无关的操作","工具返回的内容里夹带“忽略之前的指令”之类文字"],"causes":["外部内容和用户指令混在同一上下文里","agent 同时拥有读取不可信内容和执行敏感操作的权限"],"steps":["最小权限：读外部内容的 agent 不给发邮件、推代码、转账等写权限，或要求人工确认","对发帖、发送、删除等不可逆操作一律加人工确认","用 LLM Guard 等输入/输出扫描器过滤明显的注入和敏感信息外泄","上线前用 garak、PurpleLlama 等工具做红队测试，评估模型对注入的敏感度","记录完整 trace，出问题时能追溯是哪段外部内容触发的"],"notes":["扫描器只能降低风险，不能保证拦截所有注入"]},"en":{"title":"Defending agents against prompt injection from web pages and documents","summary":"There is no complete fix for prompt injection today. In practice you treat external content as untrusted data and limit the damage an agent can do after reading it.","symptoms":["After reading a web page or issue, the agent starts doing things unrelated to the task","Tool output contains text like “ignore previous instructions”"],"causes":["External content and user instructions share one context","The same agent can both read untrusted content and perform sensitive actions"],"steps":["Least privilege: an agent that reads external content gets no write access to email, code pushes or payments, or needs human approval","Require human approval for every irreversible action such as posting, sending or deleting","Filter obvious injections and data exfiltration with input/output scanners such as LLM Guard","Red-team before launch with tools like garak and PurpleLlama to see how susceptible the model is","Keep full traces so you can find which external content triggered a problem"],"notes":["Scanners reduce risk; they do not catch every injection"]},"pages":{"en":"https://aimap.page/en/problems/prompt-injection-defense/","zh-hans":"https://aimap.page/zh-hans/problems/prompt-injection-defense/"}},{"slug":"verify-mcp-server-supply-chain","type":"howto","scenario":"safe-agent-execution","needs":["DEV-09","DIS-02"],"software":["modelcontextprotocol-registry","trivy","semgrep"],"sources":[{"label":"MCP 官方调试指南 / MCP debugging guide","url":"https://modelcontextprotocol.io/docs/tools/debugging"}],"verified":"2026-10-10","zh":{"title":"安装 MCP 服务器前怎么核实它是正版、安全的","summary":"MCP 服务器以你的权限运行，等于安装了一个能被模型调用的程序。仿冒包名、恶意更新和在工具描述里藏指令（工具投毒）都出现过。","symptoms":["不确定某个 npm/PyPI 包是不是官方发布","工具描述里出现与功能无关的指令"],"causes":["直接复制网上的安装命令，没有核对来源","使用 `latest` 版本，自动拿到未经审查的更新"],"steps":["从官方仓库或 MCP 官方注册表核对包名和发布者，确认安装命令里的包名与官方一致","固定版本号，升级前看更新说明和代码差异","安装后先用 Inspector 查看全部工具及描述，留意要求读取额外文件或外发数据的内容","用 trivy 扫描依赖漏洞、semgrep 做代码检查；能用容器运行的尽量放进容器","只给服务器任务需要的令牌和目录"],"notes":[]},"en":{"title":"How to check an MCP server is genuine and safe before installing","summary":"An MCP server runs with your permissions: you are installing a program the model can call. Look-alike package names, malicious updates and instructions hidden in tool descriptions (tool poisoning) have all happened.","symptoms":["You are not sure an npm/PyPI package is the official one","A tool description contains instructions unrelated to its function"],"causes":["Install commands were copied from the web without checking the source","`latest` is used, so unreviewed updates arrive automatically"],"steps":["Check the package name and publisher against the official repository or the official MCP Registry, and make sure the install command matches","Pin versions and read release notes and diffs before upgrading","After installing, list all tools and descriptions in Inspector and look for requests to read extra files or send data out","Scan dependencies with trivy and code with semgrep; run the server in a container when possible","Give the server only the tokens and directories the task needs"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/verify-mcp-server-supply-chain/","zh-hans":"https://aimap.page/zh-hans/problems/verify-mcp-server-supply-chain/"}},{"slug":"track-claude-code-usage-cost","type":"howto","scenario":"control-ai-cost","needs":["DEV-01"],"software":["ccusage","litellm","openrouter","helicone"],"sources":[{"label":"ccusage","url":"https://github.com/ryoppippi/ccusage"},{"label":"LiteLLM budgets","url":"https://docs.litellm.ai/docs/proxy/users"}],"verified":"2026-10-10","zh":{"title":"Claude Code / Codex 用了多少、花了多少怎么查","summary":"订阅制工具的用量窗口和限额不透明，API 调用又分散在各处。本地日志分析工具和统一网关是两种主要办法。","symptoms":["不知道离限额还有多少，经常在关键时刻被限流","月底账单超出预期"],"causes":["订阅用量只在官方界面粗略显示","多个项目、多把 key 分散调用，没有汇总"],"steps":["订阅用户：用 ccusage 读取本地日志统计用量，例如运行 `npx ccusage@latest`（支持的工具和命令以项目说明为准）","API 用户：把调用统一经过 LiteLLM、OpenRouter 等网关，在一个地方看每个 key、每个项目的花费","用 Helicone 等可观测工具记录每次请求的 token 和成本","在官方后台设置用量提醒或硬上限","限额规则经常调整，以官方最新说明为准，并记下核实日期"],"notes":[]},"en":{"title":"How much have Claude Code / Codex used and cost?","summary":"Usage windows and limits on subscription tools are opaque, and API calls are scattered. Local log analysers and a unified gateway are the two main approaches.","symptoms":["You do not know how close you are to a limit and get throttled at bad moments","The monthly bill is higher than expected"],"causes":["Subscription usage is only shown roughly in the official UI","Calls are spread across projects and keys with no aggregation"],"steps":["Subscription users: analyse local logs with ccusage, e.g. `npx ccusage@latest` (supported tools and commands per the project README)","API users: route calls through a gateway such as LiteLLM or OpenRouter to see spend per key and project in one place","Record tokens and cost per request with an observability tool such as Helicone","Set usage alerts or hard caps in the provider’s console","Limit rules change often; follow the latest official terms and note the date you checked"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/track-claude-code-usage-cost/","zh-hans":"https://aimap.page/zh-hans/problems/track-claude-code-usage-cost/"}},{"slug":"team-llm-budget-rate-limit","type":"howto","scenario":"control-ai-cost","needs":["DEV-01","ENT-04","ENT-01"],"software":["litellm","portkey-ai-gateway","kong","higress"],"sources":[{"label":"LiteLLM budgets & virtual keys","url":"https://docs.litellm.ai/docs/proxy/users"}],"verified":"2026-10-10","zh":{"title":"给团队的大模型调用设预算和限流","summary":"把所有模型调用收口到一个网关，给每个人或每个项目发虚拟 key，在网关上设预算、速率限制和模型白名单。","symptoms":["某个脚本失控，一晚上烧掉大量额度","无法按人或项目分摊费用"],"causes":["大家直接使用厂商的主 key","没有统一入口，无法限流"],"steps":["部署一个 AI 网关（开源可选 LiteLLM、Portkey Gateway、Higress、Kong 等）","为每个人/项目创建虚拟 key，设置预算上限和每分钟请求数","只开放需要的模型，昂贵模型单独审批","开启用量日志，按周查看异常","厂商主 key 只保存在网关里，不发给个人"],"notes":[]},"en":{"title":"Set budgets and rate limits for a team’s LLM usage","summary":"Route every model call through one gateway, issue virtual keys per person or project, and enforce budgets, rate limits and model allow-lists there.","symptoms":["A runaway script burns a large amount of credit overnight","Costs cannot be split by person or project"],"causes":["Everyone uses the vendor’s master key directly","There is no single entry point to throttle"],"steps":["Deploy an AI gateway (open-source options include LiteLLM, Portkey Gateway, Higress and Kong)","Create virtual keys per person/project with budget caps and requests-per-minute limits","Expose only the models needed; require approval for expensive ones","Turn on usage logs and review anomalies weekly","Keep vendor master keys only in the gateway, never hand them to individuals"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/team-llm-budget-rate-limit/","zh-hans":"https://aimap.page/zh-hans/problems/team-llm-budget-rate-limit/"}},{"slug":"pdf-parser-for-rag","type":"choice","scenario":"rag-and-documents","needs":["DEV-03"],"software":["markitdown","docling","mineru","marker","unstructured"],"sources":[{"label":"MarkItDown","url":"https://github.com/microsoft/markitdown"},{"label":"Docling","url":"https://github.com/docling-project/docling"},{"label":"MinerU","url":"https://github.com/opendatalab/MinerU"}],"verified":"2026-10-10","zh":{"title":"做 RAG 用哪个 PDF/文档解析工具","summary":"RAG 的效果很大程度取决于解析质量。几款常用开源工具各有侧重，最好用自己的真实文档抽样对比。本站尚未做统一实测。","symptoms":["表格被拆散、公式乱码、页眉页脚混进正文","扫描件提取不出文字"],"causes":["用纯文本提取处理复杂版式","扫描件没有经过 OCR"],"steps":["轻量、多格式转 Markdown（Word、PPT、Excel、HTML 等）：可先试 MarkItDown","版式复杂、表格多的 PDF：可试 Docling、Marker","学术论文、公式和中文文档较多：可试 MinerU","需要统一处理大量格式并接入数据管道：可看 Unstructured","从自己的文档里挑 20 份左右，含表格、扫描件和多栏排版，逐个工具输出对比后再决定"],"notes":[]},"en":{"title":"Which PDF/document parser to use for RAG","summary":"RAG quality depends heavily on parsing. Popular open-source parsers have different strengths; compare them on a sample of your own documents. We have not run a unified test yet.","symptoms":["Tables are broken apart, formulas garbled, headers and footers mixed into body text","No text comes out of scanned files"],"causes":["Plain text extraction is used for complex layouts","Scanned files were never OCR’d"],"steps":["Lightweight conversion of many formats (Word, PowerPoint, Excel, HTML…) to Markdown: try MarkItDown first","PDFs with complex layouts and many tables: try Docling or Marker","Academic papers, formulas and Chinese documents: try MinerU","Many formats feeding a data pipeline: look at Unstructured","Pick about 20 of your own documents including tables, scans and multi-column layouts, compare each tool’s output, then decide"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/pdf-parser-for-rag/","zh-hans":"https://aimap.page/zh-hans/problems/pdf-parser-for-rag/"}},{"slug":"rag-retrieval-inaccurate","type":"howto","scenario":"rag-and-documents","needs":["DEV-03"],"software":["flagembedding","ragas","qdrant","pgvector"],"sources":[{"label":"FlagEmbedding (BGE)","url":"https://github.com/FlagOpen/FlagEmbedding"},{"label":"Ragas","url":"https://docs.ragas.io/"}],"verified":"2026-10-10","zh":{"title":"RAG 检索不准、答非所问怎么排查","summary":"先确认问题出在哪一环：解析、切分、召回还是生成。用一组固定问题量化评估，再逐环改进。","symptoms":["明明文档里有答案，模型却说找不到","检索回来的片段和问题无关"],"causes":["解析质量差，文本已经错乱","切分太碎或太大，答案被切断","只用向量检索，专有名词、编号类查询召回差","没有重排，最相关的片段排不到前面"],"steps":["抽查切分后的片段，确认文本干净、一个片段能独立表达意思","按文档结构（标题、段落）切分，并保留适度重叠","采用混合检索：关键词（BM25）+ 向量，再用重排模型（如 BGE reranker）排序","准备 30–50 个带标准答案的问题，用 Ragas 等工具评估召回和答案质量，每次改动后对比","向量库选择不是首要问题；已有 Postgres 可先用 pgvector，量大再考虑专用向量库"],"notes":[]},"en":{"title":"RAG retrieves the wrong passages: how to debug","summary":"First find which stage fails: parsing, chunking, retrieval or generation. Measure with a fixed question set, then improve one stage at a time.","symptoms":["The answer is in the documents but the model says it cannot find it","Retrieved chunks are unrelated to the question"],"causes":["Poor parsing has already garbled the text","Chunks are too small or too large, cutting the answer apart","Vector-only search recalls names and IDs poorly","No reranking, so the best chunks are not at the top"],"steps":["Spot-check chunks: the text should be clean and each chunk should make sense on its own","Chunk by document structure (headings, paragraphs) with modest overlap","Use hybrid retrieval: keyword (BM25) plus vectors, then a reranker (e.g. BGE reranker)","Prepare 30–50 questions with reference answers and evaluate retrieval and answers with a tool such as Ragas after every change","The vector store is rarely the main issue; if you already run Postgres start with pgvector, move to a dedicated store at scale"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/rag-retrieval-inaccurate/","zh-hans":"https://aimap.page/zh-hans/problems/rag-retrieval-inaccurate/"}},{"slug":"agent-memory-across-sessions","type":"choice","scenario":"rag-and-documents","needs":["DEV-10"],"software":["mem0","letta","graphiti","zep","claude-code"],"sources":[{"label":"Mem0 docs","url":"https://docs.mem0.ai/"},{"label":"Claude Code memory","url":"https://code.claude.com/docs/en/memory"}],"verified":"2026-10-10","zh":{"title":"让 agent 跨会话记住东西：用记忆层还是规则文件","summary":"编程 agent 场景下，项目级规则文件往往就够；面向终端用户的应用需要长期记忆时，再考虑专门的记忆层。","symptoms":["每次新会话都要重新解释项目背景","应用里的助手记不住用户偏好"],"causes":["会话结束后上下文全部清空，没有持久化"],"steps":["编程场景：把稳定的项目知识写进 AGENTS.md / CLAUDE.md 等规则文件，由 agent 每次自动读取","需要记录用户偏好、历史事实的应用：可评估 Mem0、Letta、Zep 等记忆层","关系和时间线重要（谁在何时说过什么）时，可看基于知识图谱的 Graphiti","注意记忆内容的隐私和删除需求，提供让用户查看和清除记忆的方式"],"notes":[]},"en":{"title":"Giving agents memory across sessions: memory layer or rules file?","summary":"For coding agents a project rules file is often enough; apps for end users that need long-term memory may need a dedicated memory layer.","symptoms":["You re-explain the project in every new session","An in-app assistant does not remember user preferences"],"causes":["Context is wiped at the end of each session with nothing persisted"],"steps":["Coding: put stable project knowledge in rules files such as AGENTS.md / CLAUDE.md that the agent reads automatically","Apps that must remember preferences and facts: evaluate memory layers such as Mem0, Letta and Zep","When relationships and timelines matter (who said what, when), look at the knowledge-graph-based Graphiti","Mind privacy and deletion: let users view and clear what is remembered"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/agent-memory-across-sessions/","zh-hans":"https://aimap.page/zh-hans/problems/agent-memory-across-sessions/"}},{"slug":"llm-regression-testing","type":"howto","scenario":"evaluate-and-monitor","needs":["DEV-04","DEV-02"],"software":["promptfoo","deepeval","inspect-ai"],"sources":[{"label":"promptfoo docs","url":"https://www.promptfoo.dev/docs/intro/"}],"verified":"2026-10-10","zh":{"title":"怎么发现模型或提示词改动后效果悄悄变差","summary":"给提示词和 agent 建一套固定的回归测试，像单元测试一样在每次改动和每次换模型前后运行。","symptoms":["换了模型版本或改了提示词后，用户反馈变差，但说不清哪里差","感觉服务商的模型“降智”了却没有证据"],"causes":["没有固定测试集，只凭感觉判断"],"steps":["从真实使用中收集 50–200 个有代表性的输入，写出期望输出或判断标准","用 promptfoo、DeepEval 或 Inspect 定义测试：精确匹配、包含关键词、JSON 结构校验、LLM 评分等","把评测放进 CI，改提示词或换模型时自动对比通过率","定期（例如每周）对线上使用的模型跑同一套测试，保留历史结果，用数据判断是否降级","公开基准只能参考，最终以自己任务上的结果为准"],"notes":[]},"en":{"title":"Catch silent quality drops after model or prompt changes","summary":"Build a fixed regression suite for prompts and agents and run it before and after every change or model switch, like unit tests.","symptoms":["After a model or prompt change users say it got worse but nobody can say how","You suspect the provider’s model got “dumber” but have no evidence"],"causes":["There is no fixed test set; judgement is based on feel"],"steps":["Collect 50–200 representative real inputs and write expected outputs or grading criteria","Define tests with promptfoo, DeepEval or Inspect: exact match, required keywords, JSON schema checks, LLM-as-judge and so on","Run evals in CI and compare pass rates whenever prompts or models change","Run the same suite against production models regularly (e.g. weekly), keep history and use the data to judge degradation","Public benchmarks are a reference only; results on your own tasks decide"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/llm-regression-testing/","zh-hans":"https://aimap.page/zh-hans/problems/llm-regression-testing/"}},{"slug":"self-host-llm-observability","type":"howto","scenario":"evaluate-and-monitor","needs":["DEV-12","ENT-01"],"software":["langfuse","phoenix","openllmetry","opentelemetry-collector"],"sources":[{"label":"Langfuse self-hosting","url":"https://langfuse.com/self-hosting"},{"label":"OpenTelemetry GenAI semantic conventions","url":"https://opentelemetry.io/docs/specs/semconv/gen-ai/"}],"verified":"2026-10-10","zh":{"title":"自建大模型可观测：记录每次调用和 agent 的 trace","summary":"把每次模型调用、工具调用的输入输出、耗时和 token 记录成 trace，出问题时才能复盘。开源方案可以自托管，数据不出内网。","symptoms":["多 agent、多步骤任务出错后不知道哪一步出了问题","不知道哪个功能最耗 token"],"causes":["只记录了最终结果，没有中间步骤","各服务日志格式不一，无法串起来"],"steps":["选择自托管平台：Langfuse（官方提供 Docker Compose 等部署方式）、Arize Phoenix 等","在应用里接入其 SDK，或用 OpenLLMetry 等基于 OpenTelemetry 的埋点","尽量遵循 OpenTelemetry GenAI 语义约定，方便以后换后端","已有 OpenTelemetry 体系的团队可以经 Collector 统一转发","注意 trace 里可能包含用户数据和密钥，设置脱敏和保留期限"],"notes":[]},"en":{"title":"Self-hosted LLM observability: trace every call and agent step","summary":"Recording every model and tool call’s input, output, latency and tokens as traces is what lets you debug. Open-source options can be self-hosted so data stays on your network.","symptoms":["When a multi-step or multi-agent task fails you cannot tell which step broke","You do not know which feature uses the most tokens"],"causes":["Only final results are logged, not intermediate steps","Each service logs in a different format and nothing links up"],"steps":["Pick a self-hosted platform: Langfuse (official Docker Compose and other deployment options), Arize Phoenix and others","Add its SDK to your app, or instrument with OpenTelemetry-based OpenLLMetry","Follow the OpenTelemetry GenAI semantic conventions so you can switch back-ends later","Teams already on OpenTelemetry can forward everything through the Collector","Traces may contain user data and secrets; configure redaction and retention"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/self-host-llm-observability/","zh-hans":"https://aimap.page/zh-hans/problems/self-host-llm-observability/"}},{"slug":"is-this-project-still-maintained","type":"howto","scenario":"choose-and-avoid-pitfalls","needs":["OSS-01","OSS-02","OSS-03"],"software":["autogen","roo-code","text-generation-inference"],"sources":[],"verified":"2026-10-10","zh":{"title":"这个开源 AI 项目还在维护吗？怎么判断","summary":"AI 开源项目更替很快，停更、归档、改名、转闭源都很常见。选型前花几分钟看几项指标，可以避免把系统建在停更的项目上。","symptoms":["issue 长期没人回复","依赖的项目突然被归档或改名"],"causes":["只看星数选型，没有看维护情况"],"steps":["看仓库是否标记为 archived（归档），以及 README 顶部有没有迁移说明","看最近一次提交和最近一次发版的日期；半年以上没有发版要警惕","看过去一年的提交者数量和 issue 关闭率，单人维护的项目风险更高","查看本站软件档案的“维护状态”“最新版本”字段（标“待核”的说明还没核实）","已停更的项目，优先看官方公告推荐的继任项目，再在同类软件里比较"],"notes":["本站档案里的维护状态来自调研数据集，会定期更新，但仍以仓库实际情况为准"]},"en":{"title":"Is this open-source AI project still maintained? How to tell","summary":"AI open-source projects turn over fast: stalls, archives, renames and moves to closed source are common. A few minutes checking some signals before you choose can save you from building on a dead project.","symptoms":["Issues go unanswered for months","A dependency is suddenly archived or renamed"],"causes":["Tools were chosen by star count without checking maintenance"],"steps":["Check whether the repository is archived and whether the README starts with a migration notice","Check the dates of the latest commit and release; be wary of no release for six months or more","Check the number of committers and the issue close rate over the past year; single-maintainer projects are riskier","See the “Maintained” and “Latest version” fields in our software profiles (“to be verified” means not yet checked)","For stalled projects, start with the successor named in the official announcement, then compare others in the same category"],"notes":["Maintenance status in our profiles comes from research datasets and is refreshed periodically; the repository itself is authoritative"]},"pages":{"en":"https://aimap.page/en/problems/is-this-project-still-maintained/","zh-hans":"https://aimap.page/zh-hans/problems/is-this-project-still-maintained/"}},{"slug":"ai-tool-license-commercial-use","type":"howto","scenario":"choose-and-avoid-pitfalls","needs":["OSS-04"],"software":["n8n","dify","langflow"],"sources":[{"label":"n8n license","url":"https://github.com/n8n-io/n8n/blob/master/LICENSE.md"},{"label":"Dify license","url":"https://github.com/langgenius/dify/blob/main/LICENSE"}],"verified":"2026-10-10","zh":{"title":"开源 AI 工具能不能商用？怎么看许可证","summary":"“代码公开”不等于“开源许可”。不少热门 AI 工具使用带附加条件的许可证，例如限制托管成 SaaS 或要求保留品牌。","symptoms":["公司法务问某个工具能否用于商业产品","项目更新后许可证变了"],"causes":["只看到 GitHub 上能下载，就默认可以随意商用"],"steps":["打开仓库根目录的 LICENSE 原文，不要只看 GitHub 侧栏的标签","区分四类：OSI 认可的开源许可（MIT、Apache-2.0 等）、源码公开但有限制的许可（如 n8n 的 Sustainable Use License）、在开源许可上附加条件（如 Dify 的许可证附加条款）、商业许可","关注许可证变更历史：查看 LICENSE 文件的提交记录","有疑问时以法务意见为准；本站档案中标“待核”的许可证尚未逐条核对"],"notes":["本页不构成法律意见"]},"en":{"title":"Can I use this open-source AI tool commercially? Reading licences","summary":"“Source available” is not the same as “open-source licence”. Many popular AI tools use licences with extra conditions, such as restricting hosted SaaS use or requiring branding to stay.","symptoms":["Legal asks whether a tool can be used in a commercial product","The licence changed after an update"],"causes":["Being downloadable from GitHub was taken to mean free for any commercial use"],"steps":["Read the LICENSE file at the repository root, not just the label in GitHub’s sidebar","Tell four groups apart: OSI-approved licences (MIT, Apache-2.0…), source-available licences with restrictions (e.g. n8n’s Sustainable Use License), open-source licences with added conditions (e.g. Dify’s additional terms) and commercial licences","Watch for licence changes by checking the commit history of the LICENSE file","When in doubt follow your legal team; licences marked “to be verified” in our profiles have not been checked one by one"],"notes":["This page is not legal advice"]},"pages":{"en":"https://aimap.page/en/problems/ai-tool-license-commercial-use/","zh-hans":"https://aimap.page/zh-hans/problems/ai-tool-license-commercial-use/"}},{"slug":"choose-an-agent-framework","type":"choice","scenario":"choose-and-avoid-pitfalls","needs":["AGT-08"],"software":["langgraph","openai-agents-python","pydantic-ai","crewai","mastra"],"sources":[],"verified":"2026-10-10","zh":{"title":"agent 框架怎么选：LangGraph、OpenAI Agents SDK、Pydantic AI、CrewAI、Mastra","summary":"框架之间没有绝对的好坏，关键看语言、对流程控制的要求、要接哪些模型和部署方式。本站没有做统一实测，下面是选型时该问的问题。","symptoms":["框架太多，不知道从哪个开始","做到一半发现框架抽象层太厚，难以调试"],"causes":["没有先明确需求就选了最热门的框架"],"steps":["先确定语言：TypeScript 团队可看 Mastra 等；Python 团队选择更多","流程需要明确的状态、分支和人工介入：看 LangGraph 这类图/状态机式框架","想要轻量、贴近某家模型官方能力：看 OpenAI Agents SDK 等厂商 SDK，注意是否支持其他厂商模型","重视类型安全和结构化输出：看 Pydantic AI","多角色协作的原型：可看 CrewAI","用同一个小任务在 2–3 个候选框架里各实现一遍，比较代码量、调试体验和可观测性支持，再看档案里的维护状态"],"notes":[]},"en":{"title":"Choosing an agent framework: LangGraph, OpenAI Agents SDK, Pydantic AI, CrewAI, Mastra","summary":"No framework is best in general; it depends on language, how much flow control you need, which models you use and how you deploy. We have not run a unified test; these are the questions to ask.","symptoms":["There are too many frameworks to know where to start","Halfway through, the abstractions are too thick to debug"],"causes":["The most popular framework was picked before the requirements were clear"],"steps":["Decide the language first: TypeScript teams can look at Mastra and others; Python teams have more choice","Flows that need explicit state, branching and human-in-the-loop: look at graph/state-machine frameworks like LangGraph","Lightweight and close to one vendor’s native features: look at vendor SDKs like the OpenAI Agents SDK, and check support for other vendors’ models","Type safety and structured output matter: look at Pydantic AI","Multi-role collaboration prototypes: consider CrewAI","Build the same small task in 2–3 candidates and compare code size, debugging and observability support, then check maintenance status in our profiles"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/choose-an-agent-framework/","zh-hans":"https://aimap.page/zh-hans/problems/choose-an-agent-framework/"}},{"slug":"find-free-llm-api","type":"howto","scenario":"free-ai-resources","needs":["IND-01","VEN-06"],"software":["openrouter","litellm","ollama"],"sources":[],"verified":"2026-10-10","zh":{"title":"哪里有免费的大模型 API，免费条件是什么","summary":"免费额度分几类：长期免费层、开放权重模型（自己部署免费）、限时免费和新用户赠送额度。免费政策变化很快，要看核实日期和具体条件。","symptoms":["想做个人项目或学习，不想先付费","用着用着免费额度没了或被限流"],"causes":["没看清免费条件：速率限制、每日额度、地区和身份限制、数据是否用于训练"],"steps":["先看本站免费模型板块：按类型、提供方、是否支持工具调用筛选，每条都有免费条件和核实日期","长期免费层通常有严格的速率和每日额度，适合学习和原型","对数据敏感的项目，看清免费层是否会把输入用于训练","想完全不受额度限制，可以用 Ollama 等在本地运行开放权重模型","经 OpenRouter、LiteLLM 等统一接口调用，额度用完时方便切换模型"],"notes":["不要使用共享账号、破解 key 等违反服务条款的“免费”渠道"]},"en":{"title":"Where to find free LLM APIs, and what the conditions are","summary":"Free access comes in several forms: permanent free tiers, open-weight models (free to self-host), limited-time offers and new-user credits. Policies change fast, so check the verification date and exact conditions.","symptoms":["You want to learn or build a side project without paying first","Free credit runs out or you get rate-limited"],"causes":["The conditions were not read: rate limits, daily quotas, region and identity restrictions, whether inputs are used for training"],"steps":["Start with our Free models section: filter by type, provider and tool calling; every entry lists free conditions and a verification date","Permanent free tiers usually have strict rate and daily limits; good for learning and prototypes","For sensitive data, check whether the free tier uses inputs for training","To avoid quotas altogether, run open-weight models locally with Ollama and similar tools","Calling through a unified API such as OpenRouter or LiteLLM makes it easy to switch models when credit runs out"],"notes":["Never use shared accounts, cracked keys or other “free” channels that violate terms of service"]},"pages":{"en":"https://aimap.page/en/problems/find-free-llm-api/","zh-hans":"https://aimap.page/zh-hans/problems/find-free-llm-api/"}},{"slug":"use-llms-compliantly-in-china","type":"howto","scenario":"use-ai-compliantly-in-china","needs":["DEV-05","IND-06","ENT-05"],"software":["alibaba-cloud-bailian","volcengine-ark","ollama","vllm"],"sources":[{"label":"国家互联网信息办公室 / Cyberspace Administration of China","url":"https://www.cac.gov.cn/"}],"verified":"2026-10-10","zh":{"title":"在中国大陆怎样合规地使用大模型","summary":"合规路径主要有两条：使用已按规定完成备案、面向境内提供服务的平台和模型；或在自有环境里部署开放权重模型。本站本期没有实测各服务在境内的可用性。","symptoms":["海外模型服务提示地区不支持、账号被封","企业需要满足数据不出境等要求"],"causes":["使用了不面向该地区提供服务的产品","通过共享账号、来路不明的中转使用海外服务，存在封号和数据泄露风险"],"steps":["面向境内用户提供生成式 AI 服务的，关注网信办公布的生成式人工智能服务备案信息（以官方发布为准）","选用面向境内提供服务的模型平台，例如阿里云百炼、火山方舟等，按其官方文档接入","对数据有严格要求的，在自有服务器上用 vLLM、Ollama 等部署许可允许的开放权重模型","许多国内模型提供 OpenAI 或 Anthropic 兼容接口，可以接入常用开发工具（见“换模型”场景）","不使用账号共享、倒卖和灰色中转"],"notes":["政策会更新，本页仅为信息整理，不构成法律意见"]},"en":{"title":"Using LLMs compliantly in mainland China","summary":"There are two main compliant paths: platforms and models that completed the required filing and serve users in China, or open-weight models deployed in your own environment. We have not tested access from mainland China in this release.","symptoms":["Overseas model services say the region is unsupported or ban the account","A company must keep data inside the country"],"causes":["The product does not serve that region","Overseas services are reached through shared accounts or unknown relays, risking bans and data leaks"],"steps":["If you provide generative AI services to users in China, follow the filing information published by the Cyberspace Administration of China (official releases are authoritative)","Use model platforms that serve mainland China, such as Alibaba Cloud Model Studio (Bailian) or Volcengine Ark, following their official docs","With strict data requirements, deploy licence-permitting open-weight models on your own servers with vLLM, Ollama and similar","Many Chinese models offer OpenAI- or Anthropic-compatible APIs that work with common developer tools (see the “Switch models” scenario)","Do not use account sharing, resold accounts or grey-market relays"],"notes":["Policies change; this page is an information summary, not legal advice"]},"pages":{"en":"https://aimap.page/en/problems/use-llms-compliantly-in-china/","zh-hans":"https://aimap.page/zh-hans/problems/use-llms-compliantly-in-china/"}},{"slug":"where-to-start-learning-llms","type":"howto","scenario":"learn-ai","needs":["IND-07"],"software":["ollama","lm-studio","jan"],"sources":[],"verified":"2026-10-10","zh":{"title":"大模型从哪里开始学：路线和教程","summary":"按目标选路径：只想会用，从 AI 入门和提示词开始；要做应用，再学 RAG、工具调用、MCP 和 agent；要做研究，补数学、深度学习和 Transformer 原理。","symptoms":["教程太多，不知道先学什么","学了概念但没有动手环境"],"causes":["没有按目标规划，东学一点西学一点"],"steps":["先在本站 AI 教育板块选一条学习路径（入门 / 开发者 / 研究者），按模块顺序学习","每个阶段配合外部优质教程清单里对应类别的课程，多数免费","尽早动手：用 Ollama、LM Studio 或 Jan 在本机跑一个小模型，边学边试","做应用的同学，学完 RAG 和工具调用后，用“给 agent 接工具”“做 RAG”场景页里的软件练手","用免费模型板块找免费 API 额度，降低练习成本"],"notes":[]},"en":{"title":"Where to start learning about LLMs: roadmap and tutorials","summary":"Choose a path by goal: to use AI, start with basics and prompting; to build apps, add RAG, tool calling, MCP and agents; for research, add maths, deep learning and Transformer internals.","symptoms":["There are too many tutorials to know where to begin","You learn concepts but have nowhere to practise"],"causes":["Learning is scattered without a plan tied to a goal"],"steps":["Pick a learning path in our AI Learning Center (beginner / developer / researcher) and follow the modules in order","Pair each stage with courses from the matching category in our curated external tutorial list; most are free","Get hands-on early: run a small model locally with Ollama, LM Studio or Jan and experiment as you learn","If you build apps, practise with the software in the “Connect tools to agents” and “RAG” scenario pages after learning RAG and tool calling","Use the Free models section to find free API credit for practice"],"notes":[]},"pages":{"en":"https://aimap.page/en/problems/where-to-start-learning-llms/","zh-hans":"https://aimap.page/zh-hans/problems/where-to-start-learning-llms/"}},{"slug":"api-relay-openrouter-safe","type":"choice","scenario":"choose-and-avoid-pitfalls","needs":["DEV-05","DEV-09","ENT-04"],"software":["openrouter","litellm","portkey-ai-gateway"],"sources":[{"label":"OpenRouter Privacy / Data Collection","url":"https://openrouter.ai/docs/guides/privacy"},{"label":"OpenRouter Zero Data Retention (ZDR)","url":"https://openrouter.ai/docs/guides/features/zdr"},{"label":"OpenRouter Privacy Policy","url":"https://openrouter.ai/privacy"},{"label":"Veridrop FAQ（中转站风险与验真）","url":"https://veridrop.org/faq"},{"label":"Veridrop：openrouter.ai 检测榜","url":"https://veridrop.org/leaderboard/openrouter.ai"},{"label":"V2EX：放弃低价中转、自建可核验网关","url":"https://www.v2ex.com/t/1231697"},{"label":"V2EX：中转站可见全部 prompt，有无端到端加密标准","url":"https://www.v2ex.com/t/1241650"},{"label":"V2EX：关于大模型中转站的两个问题","url":"https://www.v2ex.com/t/1194415"}],"verified":"2026-10-12","zh":{"title":"API 中转 / OpenRouter 安全吗","summary":"任何把请求转给上游的第三方都会看到明文 prompt 与回复（除非做端到端加密，目前主流 API 没有）。OpenRouter 是公开文档较全的聚合平台，默认不长期保存 prompt/回复，并提供 Zero Data Retention（ZDR）路由；低价不明中转站则常有掺水、虚报 token、跑路与留存风险。安全取决于你的数据敏感度、是否核验、以及付款与密钥隔离方式，而不是某个品牌口号。","symptoms":["需要国内可达或统一多家模型接口，准备用 OpenRouter 或其它中转","担心代码、客户数据或密钥被中转方留存、训练或泄露","担心低价渠道偷换模型、虚报用量，或充值后跑路"],"causes":["中转在协议上必须解密 TLS 后再转上游，天然能看到内容；所谓「零日志」多数是商业承诺，不是密码学保证（社区讨论见 V2EX）","部分中转会改写模型名、剥离能力、注入 system prompt，或 usage 字段不可信（验真工具 Veridrop 的设计目标）","大额预充值 + 不可核验账单，放大跑路与计费争议风险","密钥共享、无额度上限时，泄露一次可以刷空余额"],"steps":["先按敏感度分流：含密钥、客户隐私、未发布代码的请求，优先直连官方 API 或自建可审计的薄网关；玩具与公开资料可用聚合平台","读官方隐私说明：OpenRouter 文档写明默认不存储 prompt/回复，除非你在账户里开启日志或「允许用于改进产品」；仍会存 token 数、延迟等元数据（见 Privacy 页，asOf=2026-10-12）","需要更强约束时开启 ZDR：账户隐私设置按模型组强制，或在请求里设 `provider.zdr=true`，只路由到声明零数据保留的 endpoint；插件/联网工具另有自己的保留政策（见 ZDR 文档）","付款与密钥：小额测试再加大；为不同项目拆 key、设消费上限与速率限制；不要把主 key 发给全员。密钥放环境变量，泄露立即轮换","验真：对可疑中转用开源工具 Veridrop（thinking signature / 协议字段 / usage 指纹）做独立检测；OpenRouter 在 Veridrop 榜上有公开历史报告（中位分与分项通过率会变，以页面为准）。也可对照上游返回的 request id、模型名与账单","判断清单（可核验优于口头承诺）：模型名与参数是否被改；token 能否与上游对应；失败时会否静默换模型；有无积分/渠道多重倍率；日志记什么、存多久；能否单独吊销密钥并看账单（社区归纳见 V2EX t/1231697）"],"notes":["本页不推荐任何不明来源的「低价中转」；不构成法律或合规意见。国内使用还需遵守当地法规与上游地区限制，另见「在中国合规使用大模型」相关解决页","Veridrop 对 openrouter.ai 的最近公开检测样本日期可能早于本页核实日；分数会随新检测变化，请点进源链接核对","asOf=2026-10-12：依据当时抓取的 OpenRouter Privacy/ZDR 文档、Veridrop FAQ 与公开榜、以及可核验的 V2EX 讨论帖"]},"en":{"title":"Are API relays / OpenRouter safe?","summary":"Any third party that forwards your request to an upstream provider can see plaintext prompts and completions unless true end-to-end encryption exists (mainstream model APIs do not). OpenRouter is a well-documented aggregator: by default it does not keep prompts/responses long-term and offers Zero Data Retention (ZDR) routing. Opaque cheap relays often risk model substitution, inflated usage, exit scams, and silent logging. Safety depends on data sensitivity, verification, and how you pay and isolate keys—not on marketing claims.","symptoms":["You need one API for many models (or better reachability) via OpenRouter or another relay","You worry that code, customer data, or secrets will be retained, trained on, or leaked","You worry about substituted models, fake token counts, or prepaid balance disappearing"],"causes":["A relay must terminate TLS and can read content; “zero log” claims are usually commercial promises, not cryptography (see community threads on V2EX)","Some relays rewrite model names, strip features, inject system prompts, or return untrustworthy usage fields (what Veridrop is built to detect)","Large prepaid balances plus non-auditable billing amplify exit-scam and billing disputes","Shared keys without spend caps can empty a wallet after one leak"],"steps":["Split by sensitivity: secrets, customer PII, and unreleased code should go to official APIs or a thin self-hosted gateway you can audit; toys and public material can use aggregators","Read the vendor docs: OpenRouter states it does not store prompts/responses unless you opt into logging or “use for product improvement”; it still stores metadata such as token counts and latency (Privacy page, asOf=2026-10-12)","For stronger constraints enable ZDR: per model-group toggles in privacy settings, or `provider.zdr=true` on the request so routing stays on endpoints that declare zero retention; plugins/web tools have separate policies (ZDR docs)","Payment and keys: test with small top-ups; split keys per project with spend and rate limits; never share the master key. Keep keys in env vars and rotate on suspicion of leak","Verify: run independent checks with open-source Veridrop (thinking signatures, protocol fields, usage fingerprints) against suspicious relays; OpenRouter has a public Veridrop leaderboard history (scores change—check the live page). Also reconcile upstream request ids, model names, and invoices","A practical checklist (prefer verifiable behavior over slogans): were model name and params altered; do tokens match upstream; silent fallback on failure; multi-layer “credits/channel multipliers”; what is logged and for how long; can you revoke one key and see its bill (community summary: V2EX t/1231697)"],"notes":["This page does not endorse opaque cheap relays and is not legal advice. Regional access and compliance rules still apply","Veridrop’s public samples for openrouter.ai may be older than this page’s asOf; always open the source links","asOf=2026-10-12 based on OpenRouter Privacy/ZDR docs, Veridrop FAQ/leaderboard, and citable V2EX threads fetched that day"]},"pages":{"en":"https://aimap.page/en/problems/api-relay-openrouter-safe/","zh-hans":"https://aimap.page/zh-hans/problems/api-relay-openrouter-safe/"}},{"slug":"litellm-1-107-0-supply-chain-compromise","type":"error","scenario":"safe-agent-execution","needs":["DEV-09","ENT-06","DIS-02"],"software":["litellm","trivy","gitleaks","trufflehog"],"sources":[{"label":"LiteLLM 官方事件通报 / Official incident post (2026-10-21)","url":"https://docs.litellm.ai/blog/security-incident-oct-21-2026"},{"label":"BerriAI/litellm issue #47826（发现者的技术分析与处置步骤）","url":"https://github.com/BerriAI/litellm/issues/47826"},{"label":"PyPI：litellm 版本列表 / release history","url":"https://pypi.org/project/litellm/#history"},{"label":"SafeDep 技术分析 / technical analysis","url":"https://safedep.io/litellm-pypi-compromise-credential-stealer-backdoor"},{"label":"Wiz Blog","url":"https://www.wiz.io/blog/litellm-compromised-steals-credentials"}],"verified":"2026-10-22","zh":{"title":"LiteLLM 1.107.0 被投毒：我中招了吗，怎么处理","summary":"2026-10-21，LiteLLM 的发布流水线被攻破，PyPI 上的 litellm==1.107.0 全部 7 个 wheel 和 Docker 镜像 v1.107.0 / latest / main-latest / main-stable 被植入凭据窃取程序和远程代码加载器。官方确认：PyPI 包在线时间为北京时间 10-21 19:39–21:23（UTC 11:39–13:23），Docker 镜像为 19:46–22:20（UTC 11:46–14:20）；GitHub 上的 v1.107.0 源码标签本身不含恶意文件，此前版本都安全，已全部下架。在这段时间里没锁版本安装或拉取过镜像的环境，要按“已被入侵”处理。","symptoms":["在 10-21 晚间（北京时间）执行过不带版本号的 pip install litellm / 升级，或拉取了 latest、main-stable 等标签的 LiteLLM 镜像","`pip show litellm` 显示 1.107.0，或 site-packages 里有 cook.pth、cook.py、sitecustomize.py","存在 /tmp/remote_code_loader.lock，或有一个父进程为 1、工作目录为 / 的游离 Python 守护进程"],"causes":["攻击者先拿到内部 LiteLLM 部署日志里的开发者 GitHub CLI OAuth 令牌（官方称 Claude Code 在某些情况下会把令牌带进响应体，而响应体被记录进了日志），再用组织所有者令牌关掉分支保护，把发布工作流指向仿冒仓库 Berri-AI/litellm 并完成签名发布（官方通报，调查仍在进行）","恶意文件以 .pth 和 sitecustomize.py 形式放进 site-packages：同一环境里任何 Python 进程启动都会执行，即使从不 import litellm","窃取范围很广：SSH 密钥、云凭据、kube/docker/gh 配置、CI 密钥、浏览器密码、各类 AI 编程工具的令牌，以及 LiteLLM 代理数据库里存的各家模型 API Key"],"steps":["先确认是否受影响：`pip show litellm` 看版本；在所有虚拟环境和镜像里搜索 litellm-1.107.0.dist-info、cook.pth、sitecustomize.py；检查是否运行过镜像摘要 sha256:1bbcb1443bc962e45f5aad53fe3d2c30600e0379715fb6c664cdd3ac126c339e。找到即确认中招；找不到不代表干净（容器和 /tmp 清理会抹掉痕迹）","不要先跑 pip install：受影响环境里任何 Python 启动（包括 pip）都会再次触发恶意代码。先在 shell 里删掉每个受影响 site-packages 中的 cook.pth、cook.py、sitecustomize.py 及对应 __pycache__ 里的 .pyc，并结束持有 /tmp/remote_code_loader.lock 的守护进程","重装时固定版本 `litellm==1.106.2`（官方建议，或 1.107.0 之前任一明确版本）；更稳妥的是从头重建虚拟环境和镜像，镜像按摘要（digest）锁定，不要用 latest","假定数据已外泄并轮换：实例 / 任务 IAM 角色、LiteLLM 代理数据库里的所有模型厂商 Key、master key 和 virtual key、DATABASE_URL 密码、主机上任何进程环境变量里的密钥，以及 SSH、云、GitHub、AI 编程工具的令牌","查审计日志：例如 AWS CloudTrail 里安装时间前后该实例角色的 GetCallerIdentity 调用，以及之后来自你基础设施之外的凭据使用","以后防范：依赖锁版本并校验哈希（如 `uv pip install --require-hashes` / pip `--require-hashes`），镜像锁 digest；CI 和代理机器用最小权限、短期凭据；别把 GitHub CLI 令牌等长期凭据放在 agent 能读到、日志会记录的地方"],"notes":["本页依据 LiteLLM 官方事件通报（最后更新 2026-10-21 20:30 UTC）与发现者在官方仓库的 issue 整理；官方称每两小时更新一次，处置细节以官方页面为准","官方称使用私有企业镜像源的企业客户不受影响","本站软件库中 LiteLLM 条目的“最新版本”可能显示 GitHub 上的 v1.107.0 标签：该标签源码本身干净，但对应的 PyPI / Docker 制品是恶意的，请以本页为准，安装 1.106.2"]},"en":{"title":"LiteLLM 1.107.0 was compromised: am I affected, and what to do","summary":"On 2026-10-21 LiteLLM’s release pipeline was compromised: all seven litellm==1.107.0 wheels on PyPI and the Docker images v1.107.0 / latest / main-latest / main-stable shipped a credential stealer and a remote-code loader. Per the official post, the PyPI package was live 11:39–13:23 UTC and the Docker images 11:46–14:20 UTC; the v1.107.0 source tag on GitHub is clean, earlier versions are safe, and the artifacts have been removed. Treat any environment that installed it unpinned or pulled those images in that window as compromised.","symptoms":["You ran an unpinned pip install / upgrade of litellm, or pulled LiteLLM images tagged latest / main-stable, on 2026-10-21 between 11:39 and 14:20 UTC","`pip show litellm` reports 1.107.0, or cook.pth, cook.py or sitecustomize.py sit in site-packages","/tmp/remote_code_loader.lock exists, or there is a detached Python daemon (parent PID 1, working directory /)"],"causes":["Per LiteLLM, the attacker obtained developer GitHub CLI OAuth tokens from logs of an internal LiteLLM deployment (Claude Code can, in some cases, embed the token in a response body that then gets logged), used an org-owner token to disable branch protection, pointed the release workflow at the lookalike repo Berri-AI/litellm and published signed artifacts (investigation ongoing)","The payload is installed as a .pth file and sitecustomize.py in site-packages, so it runs whenever any Python process starts in that environment, even without importing litellm","It steals SSH keys, cloud credentials, kube/docker/gh configs, CI secrets, browser passwords, AI coding tool tokens and the provider API keys stored in the LiteLLM proxy database"],"steps":["Check exposure: `pip show litellm`; search every venv and image for litellm-1.107.0.dist-info, cook.pth and sitecustomize.py; check whether image digest sha256:1bbcb1443bc962e45f5aad53fe3d2c30600e0379715fb6c664cdd3ac126c339e ever ran. A hit confirms exposure; no hit does not prove you are clean (container and /tmp cleanup remove traces)","Do not start with pip install: any Python start in the affected environment (pip included) re-runs the payload. From the shell, delete cook.pth, cook.py, sitecustomize.py and matching __pycache__ .pyc files from every affected site-packages, and kill the daemon holding /tmp/remote_code_loader.lock","Reinstall pinned to `litellm==1.106.2` (official advice, or any explicit earlier version); better, rebuild venvs and images from scratch and pin images by digest instead of latest","Assume exfiltration and rotate: instance/task IAM roles, every provider key in the LiteLLM proxy DB plus master and virtual keys, the DATABASE_URL password, any secret in the environment of any process on the host, and SSH, cloud, GitHub and AI-tool tokens","Review audit logs, e.g. AWS CloudTrail GetCallerIdentity calls from the instance role around install time and later use of its credentials from outside your infrastructure","Going forward: pin dependencies with hashes (`uv pip install --require-hashes` / pip `--require-hashes`), pin images by digest, give CI and proxy hosts least-privilege short-lived credentials, and keep long-lived tokens such as GitHub CLI tokens out of places agents can read or logs can capture"],"notes":["Based on LiteLLM’s official incident post (last updated 2026-10-21 20:30 UTC) and the reporter’s issue in the official repo; LiteLLM says it updates the post every two hours — follow it for the latest details","LiteLLM says enterprise customers using its private registry were not affected","Our LiteLLM software entry may show the GitHub v1.107.0 tag as the latest version: the tag’s source is clean, but the matching PyPI/Docker artifacts were malicious — install 1.106.2"]},"pages":{"en":"https://aimap.page/en/problems/litellm-1-107-0-supply-chain-compromise/","zh-hans":"https://aimap.page/zh-hans/problems/litellm-1-107-0-supply-chain-compromise/"}},{"slug":"choose-ai-coding-tool","type":"choice","scenario":"ai-coding","needs":["DEV-02","IND-02"],"software":["cursor","claude-code","codex","github-copilot","cline"],"sources":[{"label":"Cursor 定价","url":"https://cursor.com/docs/account/pricing"},{"label":"GitHub Copilot 套餐","url":"https://github.com/features/copilot/plans"},{"label":"Claude 定价","url":"https://www.anthropic.com/pricing"},{"label":"Codex 定价","url":"https://developers.openai.com/codex/pricing"}],"verified":"2026-10-22","zh":{"title":"Cursor、Claude Code、Codex、Copilot 怎么选","summary":"四者都能读写整个项目，区别主要在使用形态（IDE 还是终端）、计费方式和你已有的订阅。先按形态选，再看价格。","symptoms":["不知道该订哪个，担心重复付费","试了一个觉得不顺手，不确定是工具问题还是用法问题"],"causes":["四类工具能力相近，宣传都强调“agent”","价格档位多：按月订阅、按请求、按 token 混在一起"],"steps":["想在 VS Code 式编辑器里看 diff、逐处接受修改：选 Cursor 或 GitHub Copilot","习惯终端、经常做跨多文件的大改动：选 Claude Code 或 Codex CLI","已经订阅 ChatGPT Plus 或 Claude Pro：先用其中自带的 Codex 或 Claude Code，不必再多付一份","预算最低：GitHub Copilot Pro $10/月；认证学生可免费使用 Copilot","想自带 key、接国产或本地模型：用开源的 Cline、Aider、OpenCode","无论选哪个，都在仓库根目录写 AGENTS.md，并要求 agent 改代码前先跑测试"],"notes":["价格取自本站订阅对比页（官方页面，2026-10-10/13 核实），可能已变化，以官网为准","团队采购还要看是否支持 SSO、数据不用于训练和管理后台"]},"en":{"title":"Cursor vs Claude Code vs Codex vs Copilot: which to choose","summary":"All four can read and edit a whole project. The real differences are form (IDE or terminal), billing and what you already pay for. Choose the form first, then the price.","symptoms":["You can’t decide which to buy and fear paying twice","One tool felt awkward and you’re not sure if it is the tool or your workflow"],"causes":["The tools have similar capabilities and all market “agents”","Many pricing tiers mix monthly plans, requests and tokens"],"steps":["Want diffs and per-hunk accept in a VS Code-style editor: choose Cursor or GitHub Copilot","Terminal-first, frequent multi-file changes: choose Claude Code or Codex CLI","Already paying for ChatGPT Plus or Claude Pro: use the bundled Codex or Claude Code before buying more","Lowest budget: GitHub Copilot Pro at $10/mo; verified students get Copilot free","Bring your own key, Chinese or local models: open-source Cline, Aider or OpenCode","Whatever you pick, add an AGENTS.md at the repo root and make the agent run tests before editing"],"notes":["Prices come from our subscriptions page (official pages, checked 2026-10-10/13) and may have changed; the vendor site wins","For team purchases also check SSO, no-training commitments and admin controls"]},"pages":{"en":"https://aimap.page/en/problems/choose-ai-coding-tool/","zh-hans":"https://aimap.page/zh-hans/problems/choose-ai-coding-tool/"}},{"slug":"choose-ai-assistant-subscription","type":"choice","scenario":"everyday-work-writing","needs":["IND-02"],"software":["chatgpt-desktop","claude-desktop","gemini","doubao","kimi","deepseek-chat"],"sources":[{"label":"ChatGPT 定价","url":"https://chatgpt.com/pricing"},{"label":"Claude 定价","url":"https://www.anthropic.com/pricing"},{"label":"Google AI 套餐","url":"https://one.google.com/about/ai-premium/"}],"verified":"2026-10-22","zh":{"title":"ChatGPT、Claude、Gemini 要不要付费，付哪家","summary":"大多数人的日常写作和问答，免费档已经够用；只有经常撞到次数限制、需要更强模型或深度研究等功能时，才值得订 $20 左右的一档，而且通常只需要一家。","symptoms":["同时开着好几个订阅，每个都用得不多","免费档经常提示“已达上限”"],"causes":["没有用同一任务对比过几家","不清楚各档位的实际差别"],"steps":["拿你最常做的 3 个真实任务（如写周报、改英文邮件、总结 PDF），在 2–3 家免费档上各做一遍","只在免费档明显不够时付费：ChatGPT Go $8/月、Plus $20/月；Claude Pro $20/月；Google AI Pro $19.99/月","已经重度使用 Google 文档/Gmail 选 Gemini；长文写作和改稿多选 Claude；功能最全选 ChatGPT","在国内且不想折腾网络和支付：豆包、Kimi、DeepSeek 等免费可用","每季度复盘一次，取消用得少的订阅"],"notes":["价格取自本站订阅对比页（官方页面，2026-10-10/13 核实），可能已变化，以官网为准","工作中处理公司机密前，先确认公司是否允许或已采购企业版"]},"en":{"title":"ChatGPT, Claude or Gemini: should you pay, and for which?","summary":"For most everyday writing and Q&A the free tiers are enough. A ~$20 plan is worth it only if you keep hitting limits or need stronger models or features such as deep research, and usually one plan is enough.","symptoms":["You pay for several plans and use each a little","The free tier keeps saying you have reached the limit"],"causes":["You have never compared vendors on the same task","Tier differences are unclear"],"steps":["Take your 3 most common real tasks (weekly report, fixing an English email, summarising a PDF) and run them on 2–3 free tiers","Pay only when free clearly falls short: ChatGPT Go $8/mo, Plus $20/mo; Claude Pro $20/mo; Google AI Pro $19.99/mo","Heavy Google Docs / Gmail users: Gemini; lots of long-form writing and editing: Claude; broadest features: ChatGPT","In mainland China without payment or network hassle: Doubao, Kimi, DeepSeek are free","Review every quarter and cancel what you rarely use"],"notes":["Prices come from our subscriptions page (official pages, checked 2026-10-10/13) and may have changed; the vendor site wins","Before using company confidential data, check that your employer allows it or has an enterprise plan"]},"pages":{"en":"https://aimap.page/en/problems/choose-ai-assistant-subscription/","zh-hans":"https://aimap.page/zh-hans/problems/choose-ai-assistant-subscription/"}},{"slug":"notebooklm-answers-from-my-sources","type":"howto","scenario":"personal-knowledge","needs":["DEV-03"],"software":["gemini-notebook-formerly-notebooklm","markitdown","obsidian"],"sources":[{"label":"NotebookLM：添加或发现来源","url":"https://support.google.com/notebooklm/answer/16215270"}],"verified":"2026-10-22","zh":{"title":"怎样让 AI 只根据我的资料回答（NotebookLM）","summary":"NotebookLM 只基于你添加到笔记本里的来源回答，并在回答里标出引用的原文位置，适合读书笔记、课程资料和论文。","symptoms":["通用聊天机器人的回答编造了资料里没有的内容","想对几十份 PDF 一起提问"],"causes":["通用助手会混用训练知识和你的资料","资料没有按主题整理，一个笔记本里放了不相关的内容"],"steps":["按主题新建笔记本，一个笔记本只放一个课题的资料","添加来源：PDF、网页链接、Google 文档、复制的文本等（支持的类型以官方帮助为准）","扫描版 PDF 先做 OCR 或转 Markdown，否则可能读不到文字","提问时要求“只根据来源回答，并给出引用”，点击引用编号核对原文","用生成的学习指南、时间线、音频概览做复习"],"notes":["资料会上传到 Google 服务；涉密资料改用本地知识库方案","来源数量和大小有上限，以官方帮助为准"]},"en":{"title":"Get AI to answer only from your own files (NotebookLM)","summary":"NotebookLM answers only from the sources you add to a notebook and marks where each answer comes from, which suits reading notes, course material and papers.","symptoms":["A general chatbot invented things that are not in your documents","You want to ask questions across dozens of PDFs"],"causes":["General assistants mix training knowledge with your files","Unrelated material sits in the same notebook"],"steps":["Create one notebook per topic","Add sources: PDFs, web links, Google Docs, pasted text (supported types per the official help)","OCR scanned PDFs or convert them to Markdown first, or the text may not be read","Ask it to answer only from the sources with citations, and click citation numbers to check the original","Use the generated study guides, timelines and audio overviews for revision"],"notes":["Files are uploaded to Google; use a local knowledge base for confidential material","Source count and size are limited; see the official help"]},"pages":{"en":"https://aimap.page/en/problems/notebooklm-answers-from-my-sources/","zh-hans":"https://aimap.page/zh-hans/problems/notebooklm-answers-from-my-sources/"}},{"slug":"private-chatgpt-with-ollama-open-webui","type":"howto","scenario":"run-models-locally","needs":["IND-03","DEV-08"],"software":["ollama","open-webui","lm-studio"],"sources":[{"label":"Ollama 快速开始","url":"https://docs.ollama.com/quickstart"},{"label":"Open WebUI 快速开始","url":"https://docs.openwebui.com/getting-started/quick-start/"}],"verified":"2026-10-22","zh":{"title":"在自己电脑上搭一个“私有版 ChatGPT”（Ollama + Open WebUI）","summary":"用 Ollama 在本机运行开放权重模型，再用 Open WebUI 提供类似 ChatGPT 的网页界面，对话和文件都不出本机。","symptoms":["想用 AI 处理不能上传的资料","想让家人或小团队在局域网里共用"],"causes":["云端助手需要上传数据","只装 Ollama 只有命令行界面"],"steps":["先用本站显存计算器确认能跑多大的模型；8GB 显存或 16GB 内存可以从 4–8B 模型开始","安装 Ollama，运行 `ollama run <模型名>` 下载并测试一个模型","安装 Docker，按 Open WebUI 官方 quick start 运行 `docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data ...`","浏览器打开 `http://localhost:3000`，创建管理员账号，在设置里连接本机 Ollama","不想用 Docker：LM Studio 自带图形界面和本地服务"],"notes":["一定要挂载 `-v open-webui:/app/backend/data` 数据卷，否则升级容器会丢聊天记录（官方说明）","对局域网开放时设置强密码，不要直接暴露到公网"]},"en":{"title":"Build a private ChatGPT on your own computer (Ollama + Open WebUI)","summary":"Run open-weight models locally with Ollama and get a ChatGPT-like web interface with Open WebUI; chats and files never leave your machine.","symptoms":["You need AI for data you cannot upload","You want family or a small team to share it on the LAN"],"causes":["Cloud assistants require uploads","Ollama alone only has a command line"],"steps":["Check model size with our VRAM calculator; with 8 GB VRAM or 16 GB RAM start with 4–8B models","Install Ollama and run `ollama run <model>` to download and test one","Install Docker and follow the Open WebUI quick start: `docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data ...`","Open `http://localhost:3000`, create the admin account and connect the local Ollama in settings","No Docker? LM Studio has its own GUI and local server"],"notes":["Always mount the `-v open-webui:/app/backend/data` volume or updates lose your chats (per the docs)","Use strong passwords on the LAN and never expose it directly to the internet"]},"pages":{"en":"https://aimap.page/en/problems/private-chatgpt-with-ollama-open-webui/","zh-hans":"https://aimap.page/zh-hans/problems/private-chatgpt-with-ollama-open-webui/"}},{"slug":"deploy-dify-self-hosted","type":"howto","scenario":"enterprise-private-ai","needs":["ENT-02","ENT-05"],"software":["dify","ollama","vllm","litellm"],"sources":[{"label":"Dify Docker Compose 部署","url":"https://docs.dify.ai/en/getting-started/install-self-hosted/docker-compose"}],"verified":"2026-10-22","zh":{"title":"在公司服务器上自建 Dify（Docker Compose）","summary":"Dify 可以用 Docker Compose 部署在自己的服务器上，再接入私有化模型或云端模型 API，用来搭知识库问答和内部 AI 应用。","symptoms":["想给全公司做一个内部 AI 应用平台","数据不能放到第三方 SaaS"],"causes":["SaaS 版数据在厂商云上","没有现成的私有模型接入"],"steps":["准备服务器：官方最低要求 CPU ≥ 2 核、内存 ≥ 4 GiB，装 Docker 19.03+ 和 Docker Compose 2.24.0+","按官方文档克隆最新发布版本的源码，进入 `docker` 目录，复制 `.env.example` 为 `.env`","`docker compose up -d` 启动，浏览器打开后设置管理员账号","在“模型供应商”里接入模型：内网可接 vLLM / Ollama 的 OpenAI 兼容接口，或经 LiteLLM 网关统一接入","创建知识库，上传文档，做一个问答应用小范围试用","定期按官方升级说明备份数据卷后再升级"],"notes":["Dify 使用附加条件的开源许可证，对外提供多租户 SaaS 前先读许可证","生产环境要配 HTTPS、SSO 和备份"]},"en":{"title":"Self-host Dify on company servers (Docker Compose)","summary":"Dify can be deployed on your own servers with Docker Compose and connected to private models or cloud APIs to build knowledge-base Q&A and internal AI apps.","symptoms":["You want an internal AI app platform for the company","Data cannot go to a third-party SaaS"],"causes":["The SaaS edition keeps data on the vendor cloud","No private model integration exists yet"],"steps":["Prepare a server: official minimum CPU ≥ 2 cores, RAM ≥ 4 GiB, Docker 19.03+ and Docker Compose 2.24.0+","Clone the latest release per the docs, enter `docker`, copy `.env.example` to `.env`","Run `docker compose up -d` and set up the admin account in the browser","Add models under model providers: the OpenAI-compatible API of vLLM / Ollama on the intranet, or everything through a LiteLLM gateway","Create a knowledge base, upload documents and pilot a Q&A app with a small group","Back up data volumes before upgrading per the official upgrade notes"],"notes":["Dify uses an open-source licence with extra conditions; read it before offering multi-tenant SaaS","Production needs HTTPS, SSO and backups"]},"pages":{"en":"https://aimap.page/en/problems/deploy-dify-self-hosted/","zh-hans":"https://aimap.page/zh-hans/problems/deploy-dify-self-hosted/"}},{"slug":"stop-company-data-leaking-to-ai","type":"howto","scenario":"enterprise-private-ai","needs":["ENT-02","ENT-06"],"software":["litellm","open-webui","librechat","langfuse"],"sources":[{"label":"OpenAI 企业隐私","url":"https://openai.com/enterprise-privacy/"},{"label":"Google Workspace 生成式 AI 隐私中心","url":"https://support.google.com/a/answer/15706919"},{"label":"Anthropic 商业条款","url":"https://www.anthropic.com/legal/commercial-terms"}],"verified":"2026-10-22","zh":{"title":"员工把公司资料贴进 AI 怎么办","summary":"一刀切禁止通常挡不住，员工会改用个人账号。更有效的做法是提供一个合规的官方入口（企业版或私有化部署），再配合数据分级和审计。","symptoms":["发现员工用个人账号处理客户资料、代码","不清楚哪些 AI 服务会用输入数据训练模型"],"causes":["没有公司认可的 AI 工具，员工只能用个人版","个人版和企业版的数据条款不同"],"steps":["做数据分级：公开、内部、机密、受监管数据，各级能用哪些 AI 写清楚","提供官方入口：采购 ChatGPT Enterprise / Gemini for Workspace / Claude 企业版等（官方承诺默认不用企业数据训练），或私有化部署 Open WebUI / LibreChat + 内部模型","所有调用经 LiteLLM 等网关，统一 key、记录审计日志（Langfuse）","在网关或终端做敏感信息检测（身份证、手机号、源代码密钥）","发一页纸的 AI 使用规范并培训，每季度复查"],"notes":["各家数据条款会更新，签约前以官方条款原文为准","受监管行业还要满足本行业的数据出境、留存规定"]},"en":{"title":"Employees paste company data into AI: what to do","summary":"Blanket bans rarely work; people switch to personal accounts. It works better to provide an approved route (enterprise plan or private deployment) plus data classification and auditing.","symptoms":["Staff use personal accounts for customer data or code","You are unsure which AI services train on inputs"],"causes":["There is no approved AI tool, so people use consumer versions","Consumer and enterprise data terms differ"],"steps":["Classify data (public, internal, confidential, regulated) and state which AI may handle each level","Provide an approved route: ChatGPT Enterprise / Gemini for Workspace / Claude enterprise plans (officially no training on business data by default), or a private Open WebUI / LibreChat with internal models","Send every call through a gateway such as LiteLLM with central keys and audit logs (Langfuse)","Detect sensitive data (IDs, phone numbers, secrets in code) at the gateway or endpoint","Publish a one-page AI policy, train staff and review quarterly"],"notes":["Vendor terms change; rely on the contract text when signing","Regulated industries must also meet sector rules on data transfer and retention"]},"pages":{"en":"https://aimap.page/en/problems/stop-company-data-leaking-to-ai/","zh-hans":"https://aimap.page/zh-hans/problems/stop-company-data-leaking-to-ai/"}},{"slug":"transcribe-meetings-locally","type":"howto","scenario":"meetings-and-team-workflow","needs":[],"software":["faster-whisper","whisper","whisperx"],"sources":[{"label":"faster-whisper（官方仓库）","url":"https://github.com/SYSTRAN/faster-whisper"},{"label":"OpenAI Whisper（官方仓库）","url":"https://github.com/openai/whisper"}],"verified":"2026-10-22","zh":{"title":"会议录音在本地转文字（Whisper / faster-whisper）","summary":"敏感会议不想上传到云端时，可以在自己电脑上用 Whisper 系列模型转写，再交给本地或可信的模型做摘要。","symptoms":["会议内容涉密，不能用云端纪要工具","有大量历史录音要批量转写"],"causes":["云端工具需要上传音频","原版 Whisper 在 CPU 上较慢"],"steps":["安装 Python，`pip install faster-whisper`（官方称同精度下比 openai/whisper 快至多 4 倍、内存更省）","有 NVIDIA 显卡用 GPU；没有显卡用 int8 量化在 CPU 上跑","先用 small / medium 模型试速度，再换 large 系列提高准确率","需要区分说话人时用 WhisperX（带说话人分离）","转写稿交给本地模型（如 Ollama）按“结论 / 待办 / 未决问题”模板出纪要，人工校对人名和数字"],"notes":["录音前告知参会者","模型对专有名词容易出错，可以在提示里给出术语表"]},"en":{"title":"Transcribe meeting recordings locally (Whisper / faster-whisper)","summary":"When sensitive meetings must not be uploaded, transcribe them on your own computer with Whisper-family models, then summarise with a local or trusted model.","symptoms":["Meetings are confidential, so cloud notetakers are out","You have a backlog of recordings to transcribe"],"causes":["Cloud tools need audio uploads","The original Whisper is slow on CPU"],"steps":["Install Python and `pip install faster-whisper` (officially up to 4× faster than openai/whisper at the same accuracy, with less memory)","Use the GPU if you have NVIDIA; otherwise run int8 on CPU","Try small / medium models for speed, then large models for accuracy","Use WhisperX when you need speaker diarisation","Summarise the transcript with a local model (e.g. Ollama) into decisions / actions / open questions and proof names and numbers"],"notes":["Tell participants before recording","Models get proper nouns wrong; give a glossary in the prompt"]},"pages":{"en":"https://aimap.page/en/problems/transcribe-meetings-locally/","zh-hans":"https://aimap.page/zh-hans/problems/transcribe-meetings-locally/"}},{"slug":"comfyui-generate-images-locally","type":"howto","scenario":"create-images-video","needs":[],"software":["comfyui","fooocus","invokeai"],"sources":[{"label":"ComfyUI 系统要求","url":"https://docs.comfy.org/installation/system_requirements"},{"label":"ComfyUI（官方仓库）","url":"https://github.com/comfyanonymous/ComfyUI"}],"verified":"2026-10-22","zh":{"title":"在自己电脑上用 ComfyUI 生成图片","summary":"ComfyUI 是节点式的本地生图工具，不限次数、可复现、能批量；新手也可以先用更简单的 Fooocus 或 InvokeAI。","symptoms":["云端生图积分不够用","需要固定风格、批量出图或可复现的流程"],"causes":["云端服务按次计费、风格难以完全复现","本地部署看起来门槛高"],"steps":["确认硬件：官方推荐 NVIDIA 或 AMD 显卡（Windows），macOS 需 Apple Silicon","下载 Comfy Desktop（Windows / macOS / Linux）或 Windows 便携版，一键安装","从官方模板打开一个文生图工作流，按提示下载对应模型","把满意的工作流保存为 JSON，之后批量改提示词复用","想更简单：Fooocus 只需写提示词；InvokeAI 有画布式界面"],"notes":["下载模型时看清许可证是否允许商用","只从官方或模型作者的发布页下载模型和自定义节点"]},"en":{"title":"Generate images locally with ComfyUI","summary":"ComfyUI is a node-based local image generator: unlimited, reproducible and batch-friendly. Beginners can start with simpler Fooocus or InvokeAI.","symptoms":["Cloud credits run out","You need a fixed style, batches or reproducible pipelines"],"causes":["Cloud services charge per image and are hard to reproduce exactly","Local setup looks intimidating"],"steps":["Check hardware: NVIDIA or AMD GPU recommended on Windows; macOS needs Apple Silicon (official requirements)","Download Comfy Desktop (Windows / macOS / Linux) or the Windows portable build","Open a text-to-image workflow from the official templates and download the models it asks for","Save good workflows as JSON and reuse them with new prompts in batches","Simpler options: Fooocus needs only a prompt; InvokeAI has a canvas UI"],"notes":["Check each model’s licence for commercial use","Download models and custom nodes only from official or author release pages"]},"pages":{"en":"https://aimap.page/en/problems/comfyui-generate-images-locally/","zh-hans":"https://aimap.page/zh-hans/problems/comfyui-generate-images-locally/"}},{"slug":"label-ai-generated-content-china","type":"howto","scenario":"create-images-video","needs":["DIS-05"],"software":["jimeng","kling","capcut","doubao"],"sources":[{"label":"《人工智能生成合成内容标识办法》（国家网信办）","url":"https://www.cac.gov.cn/2025-03/14/c_1743654684782215.htm"}],"verified":"2026-10-22","zh":{"title":"在国内平台发 AI 生成的图片、视频要怎么标识","summary":"《人工智能生成合成内容标识办法》自 2025 年 9 月 1 日起施行：用户发布 AI 生成合成内容时，应当主动声明，并使用平台提供的标识功能；不得删除或篡改标识。","symptoms":["发布的视频被平台提示“疑似 AI 生成”或被限流","不确定 AI 修图、配音算不算要标识"],"causes":["办法要求服务提供者添加显式和隐式标识，用户发布时主动声明","去水印或二次处理可能破坏隐式标识"],"steps":["发布时在平台的“AI 生成内容”声明选项中勾选（各平台位置不同）","保留生成工具自动加的显式标识（文字提示、角标等），不要裁掉或遮挡","不要用工具删除、篡改元数据里的隐式标识","对文本、音频、图片、视频都适用；配音、换脸、数字人尤其要声明","商用素材还要另外确认生成工具的商用授权"],"notes":["本文只概括办法原文的要点，不构成法律意见；以原文和平台规则为准","海外平台（YouTube、TikTok 等）也有各自的 AI 内容披露规则"]},"en":{"title":"Labelling AI-generated images and video on Chinese platforms","summary":"China’s Measures for Labelling AI-Generated Synthetic Content took effect on 1 September 2025: users who publish AI-generated content must declare it and use the platform’s labelling tools, and must not remove or alter labels.","symptoms":["A platform flags your video as possibly AI-generated or limits its reach","You are unsure whether AI retouching or voice-over needs a label"],"causes":["The measures require providers to add explicit and implicit labels and users to declare when publishing","Removing watermarks or re-processing can strip implicit labels"],"steps":["Tick the platform’s AI-generated content declaration when publishing (location varies by platform)","Keep the explicit labels generators add (text notes, badges); do not crop or cover them","Do not remove or alter implicit labels in metadata","It applies to text, audio, images and video; voice-overs, face swaps and digital humans especially need a declaration","For commercial use also confirm the generator’s commercial licence"],"notes":["This summarises the official text and is not legal advice; the original text and platform rules prevail","Overseas platforms (YouTube, TikTok…) have their own AI disclosure rules"]},"pages":{"en":"https://aimap.page/en/problems/label-ai-generated-content-china/","zh-hans":"https://aimap.page/zh-hans/problems/label-ai-generated-content-china/"}},{"slug":"disclose-ai-use-in-papers","type":"howto","scenario":"research-literature","needs":["IND-07"],"software":["chatgpt-desktop","claude-desktop","gemini-notebook-formerly-notebooklm"],"sources":[{"label":"Nature Portfolio AI 政策","url":"https://www.nature.com/nature-portfolio/editorial-policies/ai"},{"label":"ICMJE：作者使用 AI","url":"https://www.icmje.org/recommendations/browse/artificial-intelligence/ai-use-by-authors.html"},{"label":"Elsevier 期刊生成式 AI 政策","url":"https://www.elsevier.com/about/policies-and-standards/generative-ai-policies-for-journals"}],"verified":"2026-10-22","zh":{"title":"论文里用了 AI，要怎么披露","summary":"主流期刊和 ICMJE 的共同要求：AI 不能署名作者；用 AI 辅助写作或分析要在投稿时说明怎么用的；作者对全部内容负责。具体位置和措辞以目标期刊政策为准。","symptoms":["不确定润色语言要不要声明","担心用了 AI 被拒稿"],"causes":["各期刊政策细节不同","把 AI 生成的引用、数据直接放进论文会构成学术不端"],"steps":["投稿前读目标期刊的 AI 政策（Nature、Elsevier 等都有专门页面）","记录用过的工具、版本和用途（如“用 ChatGPT 润色英文”“用 AI 辅助代码”）","按 ICMJE 建议在投稿信和论文相应部分（方法、致谢等）说明 AI 的使用方式","不要把 AI 列为作者；AI 生成的图片通常受严格限制","逐条核对 AI 给出的事实和引用，确保没有抄袭"],"notes":["各期刊、学校规定会更新，以最新官方政策为准"]},"en":{"title":"How to disclose AI use in a paper","summary":"Major journals and ICMJE agree: AI cannot be an author; describe how AI assisted writing or analysis when you submit; authors are responsible for everything. Exact placement and wording follow the target journal’s policy.","symptoms":["You are unsure whether language polishing must be declared","You worry AI use will get the paper rejected"],"causes":["Policies differ by journal","Putting AI-generated citations or data into a paper is misconduct"],"steps":["Read the target journal’s AI policy before submitting (Nature, Elsevier and others have dedicated pages)","Record tools, versions and purposes (e.g. “ChatGPT for English editing”, “AI-assisted code”)","Per ICMJE, describe AI use in the cover letter and the relevant section of the paper (methods, acknowledgements…)","Never list AI as an author; AI-generated images are usually tightly restricted","Check every AI-provided fact and citation and make sure nothing is plagiarised"],"notes":["Journal and university rules change; follow the latest official policy"]},"pages":{"en":"https://aimap.page/en/problems/disclose-ai-use-in-papers/","zh-hans":"https://aimap.page/zh-hans/problems/disclose-ai-use-in-papers/"}},{"slug":"ai-fake-citations","type":"error","scenario":"research-literature","needs":[],"software":["perplexity","gemini-notebook-formerly-notebooklm","llm-for-zotero"],"sources":[{"label":"Crossref REST API","url":"https://www.crossref.org/documentation/retrieve-metadata/rest-api/"},{"label":"Semantic Scholar API","url":"https://api.semanticscholar.org/api-docs/"},{"label":"ICMJE：作者使用 AI","url":"https://www.icmje.org/recommendations/browse/artificial-intelligence/ai-use-by-authors.html"}],"verified":"2026-10-22","zh":{"title":"AI 给的参考文献查不到（编造引用）","summary":"大模型会生成格式完美但并不存在的文献，或把真实作者、期刊和错误标题拼在一起。所有 AI 给出的引用都必须逐条核实。","symptoms":["在数据库里搜不到 AI 给的论文标题","DOI 打不开或指向另一篇文章"],"causes":["模型按“看起来像引用”的模式生成文本，而不是查数据库","没有联网检索或检索结果没被正确引用"],"steps":["把每条引用的标题或 DOI 放到 Crossref、Semantic Scholar、Google Scholar 或知网里查","DOI 打开后核对作者、年份、期刊是否一致","只引用自己读过原文（至少摘要）的文献","改用基于来源的工具：先自己找到文献放进 NotebookLM 或 Zotero，再让 AI 只在这些文献里回答","投稿前把参考文献列表整体再核一遍"],"notes":["ICMJE 指出 AI 可能产生错误、不完整或有偏见的内容，作者必须审核"]},"en":{"title":"AI-generated references that don’t exist","summary":"LLMs can produce perfectly formatted references that do not exist, or mix real authors and journals with wrong titles. Verify every AI-provided citation.","symptoms":["The title can’t be found in any database","The DOI fails or points to another article"],"causes":["Models generate text that looks like a citation instead of querying a database","No web retrieval, or retrieved results were cited incorrectly"],"steps":["Look up each title or DOI in Crossref, Semantic Scholar, Google Scholar or CNKI","Open the DOI and check authors, year and journal","Cite only what you have read (at least the abstract)","Use source-grounded tools: find papers yourself, add them to NotebookLM or Zotero, and let AI answer only from them","Re-check the whole reference list before submission"],"notes":["ICMJE notes AI output can be incorrect, incomplete or biased and authors must review it"]},"pages":{"en":"https://aimap.page/en/problems/ai-fake-citations/","zh-hans":"https://aimap.page/zh-hans/problems/ai-fake-citations/"}},{"slug":"secure-vibe-coded-app","type":"howto","scenario":"build-apps-without-code","needs":[],"software":["lovable","v0","bolt","replit"],"sources":[{"label":"Lovable 安全概览","url":"https://docs.lovable.dev/features/security"},{"label":"Supabase 行级安全（RLS）","url":"https://supabase.com/docs/guides/database/postgres/row-level-security"}],"verified":"2026-10-22","zh":{"title":"Vibe coding 做的应用上线前怎么做安全检查","summary":"用自然语言生成的应用最常见的问题是数据库没开权限控制、API key 写在前端。上线前至少做三件事：开启行级安全、移走密钥、跑一次安全扫描。","symptoms":["任何人拿到网页里的公开 key 就能读写全部数据","账单突然暴涨（key 被盗用）"],"causes":["数据库表没开启行级安全（RLS），或策略过宽","第三方 API key 被写进了前端代码"],"steps":["用 Supabase 的话：每张表执行 `alter table ... enable row level security`，开启后在没有策略前，用公开 key 通过 API 读不到任何数据（官方说明）","按角色写最小策略：未登录用户默认什么都拿不到，登录用户只能读写自己的行","把第三方 API key 放到服务端函数或平台的密钥管理里，前端不出现任何密钥","发布前运行平台自带的安全扫描（Lovable 提供 quick scan / deep scan），逐条处理发现的问题","用另一个浏览器、未登录状态实际测一遍能否看到别人的数据"],"notes":["涉及支付、医疗、个人敏感信息的应用，上线前请专业开发者审查"]},"en":{"title":"Security checks before launching a vibe-coded app","summary":"The most common problems in AI-generated apps are databases without access control and API keys in front-end code. Before launch, at least enable row-level security, move secrets server-side and run a security scan.","symptoms":["Anyone with the public key in your page can read and write all data","A sudden bill spike (stolen key)"],"causes":["Tables have no row-level security (RLS) or overly broad policies","Third-party API keys were put in front-end code"],"steps":["With Supabase, run `alter table ... enable row level security` on every table; once enabled, no data is accessible through the API with the publishable key until you add policies (per the docs)","Write least-privilege policies: signed-out users get nothing, signed-in users only their own rows","Move third-party API keys into server functions or the platform’s secrets store; no secrets in the front end","Run the built-in security scan before publishing (Lovable offers quick and deep scans) and fix each finding","Test in another browser while signed out to confirm you can’t see others’ data"],"notes":["Apps handling payments, health or sensitive personal data need a professional review before launch"]},"pages":{"en":"https://aimap.page/en/problems/secure-vibe-coded-app/","zh-hans":"https://aimap.page/zh-hans/problems/secure-vibe-coded-app/"}},{"slug":"free-ai-for-students","type":"howto","scenario":"study-with-ai","needs":["IND-04","IND-01"],"software":["github-copilot","gemini-notebook-formerly-notebooklm","doubao","kimi","deepseek-chat"],"sources":[{"label":"GitHub：学生免费使用 Copilot","url":"https://docs.github.com/en/copilot/how-tos/copilot-on-github/set-up-copilot/enable-copilot/set-up-for-students"},{"label":"GitHub Student Developer Pack","url":"https://education.github.com/pack"},{"label":"NotebookLM：添加来源","url":"https://support.google.com/notebooklm/answer/16215270"}],"verified":"2026-10-22","zh":{"title":"学生能免费用哪些 AI 工具","summary":"学生不必花钱也能用上大部分 AI：主流助手的免费档、NotebookLM、本地开源模型；学编程还可以通过 GitHub 学生认证免费使用 Copilot。","symptoms":["预算有限，不想订阅","不知道学生身份能领哪些福利"],"causes":["学生福利分散在各家官网，条件和期限经常变","部分限时活动容易过期"],"steps":["用学校邮箱和学生证明申请 GitHub Student Developer Pack；认证后按 GitHub 文档开通免费 Copilot","日常讲解和写作辅导：豆包、Kimi、DeepSeek、Gemini、ChatGPT 免费档","复习：NotebookLM 上传讲义生成提纲和自测题（免费）","想无限次用：在自己电脑上用 Ollama / LM Studio 跑开放模型","问学校信息中心或图书馆是否有机构版 AI 账号","看本站免费 API 页的核实日期，限时活动以官网为准"],"notes":["各家学生优惠的条件、地区和期限会变化，以官网为准","使用前先了解学校对作业使用 AI 的规定"]},"en":{"title":"Free AI tools for students","summary":"Students can use most AI without paying: free tiers of major assistants, NotebookLM and local open models; for coding, GitHub student verification unlocks Copilot for free.","symptoms":["Tight budget, no subscription","You don’t know which perks students get"],"causes":["Student perks are scattered across vendor sites and change often","Limited-time offers expire"],"steps":["Apply for the GitHub Student Developer Pack with your school email and proof of enrolment, then enable free Copilot per GitHub’s docs","Explanations and writing help: free tiers of Doubao, Kimi, DeepSeek, Gemini and ChatGPT","Revision: upload lecture notes to NotebookLM for outlines and quizzes (free)","Unlimited use: run open models locally with Ollama / LM Studio","Ask your school IT or library about institutional AI accounts","Check verification dates on our Free API page; limited-time offers per vendor sites"],"notes":["Student offers change by condition, region and period; the vendor site wins","Know your school’s rules on AI in assignments first"]},"pages":{"en":"https://aimap.page/en/problems/free-ai-for-students/","zh-hans":"https://aimap.page/zh-hans/problems/free-ai-for-students/"}}]}