[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-a16z-infra--companion-app":3,"tool-a16z-infra--companion-app":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",157379,2,"2026-04-15T23:32:42",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":72,"owner_avatar_url":73,"owner_bio":74,"owner_company":74,"owner_location":74,"owner_email":74,"owner_twitter":74,"owner_website":74,"owner_url":75,"languages":76,"stars":96,"forks":97,"last_commit_at":98,"license":99,"difficulty_score":100,"env_os":101,"env_gpu":102,"env_ram":103,"env_deps":104,"category_tags":117,"github_topics":74,"view_count":32,"oss_zip_url":74,"oss_zip_packed_at":74,"status":17,"created_at":118,"updated_at":119,"faqs":120,"releases":156},7889,"a16z-infra\u002Fcompanion-app","companion-app","AI companions with memory: a lightweight stack to create and host your own AI companions","companion-app 是一个轻量级的开源技术栈，旨在帮助开发者快速构建并部署拥有“记忆”功能的专属 AI 伴侣。它解决了传统聊天机器人缺乏上下文连贯性和个性化深度的问题，让用户能够自定义角色的性格与背景故事，并通过浏览器或短信进行自然交互。\n\n该项目特别适合对聊天机器人架构感兴趣的开发者及技术爱好者，作为学习如何从零搭建 AI 应用的教学范例。其核心技术亮点在于结合了向量数据库（如 Pinecone 或 Supabase pgvector）进行相似度搜索，以检索相关背景知识；同时利用队列机制存储对话历史，赋予 AI 长期的记忆能力，使交流更具深度。此外，它支持集成 ChatGPT 和 Vicuna 等多种大语言模型，并提供了完整的身份认证、流式文本输出及 Twilio 短信对接方案。需要注意的是，companion-app 主要定位为开发教程和启动模板，若需生产级平台可参考其他成熟项目，但它无疑是探索 AI 伴侣开发原理的理想起点。","# AI Companion App (based on AI Getting Started template)\n\n[Live Demo](https:\u002F\u002Fai-companion-stack.com\u002F)\n\n[Join our community Discord: AI Stack Devs](https:\u002F\u002Fdiscord.gg\u002FPQUmTBTGmT)\n\n\u003Cimg width=\"1182\" alt=\"Screen Shot 2023-07-10 at 11 27 03 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_45baabd7e92c.png\">\n\n\nThis is a tutorial stack to create and host AI companions that you can chat with on a browser or text via SMS. It allows you to determine the personality and backstory of your companion, and uses a vector database with similarity search to retrieve and prompt so the conversations have more depth. It also provides some conversational memory by keeping the conversation in a queue and including it in the prompt. \n\nIt currently contains companions on both ChatGPT and Vicuna hosted on [Replicate](https:\u002F\u002Freplicate.com\u002F). \n\nThere are many possible use cases for these companions - romantic (AI girlfriends \u002F boyfriends), friendship, entertainment, coaching, etc. You can guide your companion towards your ideal use case with the backstory you write and the model you choose.\n\n**Note** This project is purely intended to be a developer tutorial and starter stack for those curious on how chatbots are built. If you're interested in what a production open source platform looks like, check out [Steamship](https:\u002F\u002Fwww.steamship.com\u002F). Or what the leading AI chat platforms look like, check out [Character.ai](https:\u002F\u002Fbeta.character.ai\u002F).\n\n## Overview\n\n- 💻 [Stack](#stack)\n- 🧠 [Quickstart](#quickstart)\n- 🚀 [How does this work?](#how-does-this-work)\n- 👤 [Adding\u002Fmodifying characters](#addingmodifying-characters)\n- 👩‍💻 [How to contribute to this repo](#how-to-contribute-to-this-repo)\n- 🐍 [Python support](#python-support)\n- 💽 [Exporting your companion to Character.ai](#export-to-characterai)\n\n## Stack\n\nThe stack is based on the [AI Getting Started Stack](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-getting-started):\n\n- Auth: [Clerk](https:\u002F\u002Fclerk.com\u002F)\n- App logic: [Next.js](https:\u002F\u002Fnextjs.org\u002F)\n- VectorDB: [Pinecone](https:\u002F\u002Fwww.pinecone.io\u002F) \u002F [Supabase pgvector](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Fdatabase\u002Fextensions\u002Fpgvector)\n- LLM orchestration: [Langchain.js](https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002F)\n- Text model: [OpenAI](https:\u002F\u002Fplatform.openai.com\u002Fdocs\u002Fmodels), [Replicate (Vicuna13b)](https:\u002F\u002Freplicate.com\u002Freplicate\u002Fvicuna-13b)\n- Text streaming: [ai sdk](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fai)\n- Conversation history: [Upstash](https:\u002F\u002Fupstash.com\u002F)\n- Deployment: [Fly](https:\u002F\u002Ffly.io\u002F)\n- Text with companion: [Twilio](https:\u002F\u002Ftwilio.com\u002F)\n\n## Quickstart\n\nThe following instructions should get you up and running with a fully\nfunctional, local deployment of four AIs to chat with. Note that the companions\nrunning on Vicuna (Rosie and Lucky) will take more time to respond as we've not\ndealt with the cold start problem. So you may have to wait around a bit :)\n\n### 1. Fork and Clone repo\n\nFork the repo to your Github account, then run the following command to clone the repo:\n\n```\ngit clone git@github.com:[YOUR_GITHUB_ACCOUNT_NAME]\u002Fcompanion-app.git\n```\n\n**Alternatively**, you can launch the app quickly through Github Codespaces by clicking on \"Code\" -> \"Codespaces\" -> \"+\"\n\u003Cimg width=\"458\" alt=\"Screen Shot 2023-07-10 at 11 04 04 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_2790eef58443.png\">\n\nIf you choose to use Codespaces, npm dependencies will be installed automatically and you can proceed to step 3. \n\n### 2. Install dependencies\n\n```\ncd companion-app\nnpm install\n```\n\n### 3. Fill out secrets\n\n```\ncp .env.local.example .env.local\n```\n\nSecrets mentioned below will need to be copied to `.env.local`\n\na. **Clerk Secrets**\n\nGo to https:\u002F\u002Fdashboard.clerk.com\u002F -> \"Add Application\" -> Fill in Application name\u002Fselect how your users should sign in -> Create Application\nNow you should see both `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` on the screen\n\u003Cimg width=\"1398\" alt=\"Screen Shot 2023-07-10 at 11 04 57 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_bb01c8275648.png\">\n\nIf you want to text your AI companion in later steps, you should also enable \"phone number\" under \"User & Authentication\" -> \"Email, Phone, Username\" on the left hand side nav:\n\n\u003Cimg width=\"1013\" alt=\"Screen Shot 2023-07-10 at 11 05 42 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_f47846ccc077.png\">\n\n\nb. **OpenAI API key**\n\nVisit https:\u002F\u002Fplatform.openai.com\u002Faccount\u002Fapi-keys to get your OpenAI API key if you're using OpenAI for your language model.\n\nc. **Replicate API key**\n\nVisit https:\u002F\u002Freplicate.com\u002Faccount\u002Fapi-tokens to get your Replicate API key if you're using Vicuna for your language model.\n\n\n❗ **_NOTE:_** By default, this template uses Pinecone as vector store, but you can turn on Supabase pgvector easily by uncommenting `VECTOR_DB=supabase` in `.env.local`. This means you only need to fill out either Pinecone API key _or_ Supabase API key.\n\nd. **Pinecone API key**\n\n- Create a Pinecone index by visiting https:\u002F\u002Fapp.pinecone.io\u002F and click on \"Create Index\"\n- Give it an index name (this will be the environment variable `PINECONE_INDEX`)\n- Fill in Dimension as `1536`\n- Once the index is successfully created, click on \"API Keys\" on the left side nav and create an API key: copy \"Environment\" value to `PINECONE_ENVIRONMENT` variable, and \"Value\" to `PINECONE_API_KEY`\n\ne. **Upstash API key**\n\n- Sign in to [Upstash](https:\u002F\u002Fupstash.com\u002F)\n- Under \"Redis\" on the top nav, click on \"Create Database\"\n- Give it a name, and then select regions and other options based on your preference. Click on \"Create\"\n\u003Cimg width=\"507\" alt=\"Screen Shot 2023-07-10 at 11 06 36 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_aaf79e7752dc.png\">\n\n- Scroll down to \"REST API\" section and click on \".env\". Now you can copy paste both environment variables to your `.env.local`\n\u003Cimg width=\"866\" alt=\"Screen Shot 2023-07-10 at 11 07 21 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_151f82ebefa4.png\">\n\n\nf. **Supabase API key** (optional)\nIf you prefer to use Supabase, you will need to uncomment `VECTOR_DB=supabase` and fill out the Supabase credentials in `.env.local`.\n\n- Create a Supabase instance [here](https:\u002F\u002Fsupabase.com\u002Fdashboard\u002Fprojects); then go to Project Settings -> API\n- `SUPABASE_URL` is the URL value under \"Project URL\"\n- `SUPABASE_PRIVATE_KEY` is the key starts with `ey` under Project API Keys\n- Now, you should enable pgvector on Supabase and create a schema. You can do this easily by clicking on \"SQL editor\" on the left hand side on Supabase UI and then clicking on \"+New Query\". Copy paste [this code snippet](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-getting-started\u002Fblob\u002Fmain\u002Fpgvector.sql) in the SQL editor and click \"Run\".\n\ng. **Steamship API key**\n\nYou can connect a Steamship agent instance as an LLM with personality, voice and image generation capabilities built in. It also includes its own vector storage and tools. To do so:\n\n- Create an account on [Steamship](https:\u002F\u002Fsteamship.com\u002Faccount)\n- Copy the API key from your account settings page\n- Add it as the `STEAMSHIP_API_KEY` variable \n\nIf you'd like to create your own character personality, add a custom voice, or use a different image model, visit [Steamship Agent Guidebook](https:\u002F\u002Fwww.steamship.com\u002Flearn\u002Fagent-guidebook), create your own instance and connect it in `companions.json` using the *Rick* example as a guide.\n\n### 4. Generate embeddings\n\nThe `companions\u002F` directory contains the \"personalities\" of the AIs in .txt files. To generate embeddings and load them into the vector database to draw from during the chat, run the following command:\n\n#### If using Pinecone\n\n```bash\nnpm run generate-embeddings-pinecone\n```\n\n#### If using Supabase pgvector\n\n```bash\nnpm run generate-embeddings-supabase\n```\n\n### 5. Run app locally\n\nNow you are ready to test out the app locally! To do this, simply run `npm run dev` under the project root.\n\nYou can connect to the project with your browser typically at http:\u002F\u002Flocalhost:3000\u002F.\n\n### 6. Additional feature: Text your companions\n\nYou can assign a phone number to the character you are talking to and retain the full conversational history and context when texting them. Any user can only start texting the AI companion after verifying their phone number on Clerk (you can do this by clicking on your profile picture on the companion app -> Manage Account -> Phone Number). Below are instructions on how to set up a Twilio account to send\u002Freceive messages on behalf of the AI companion:\n\na. Create a Twilio account.\n\nb. Once you created an account, create a Twilio phone number.\n\nc. On [Twilio dashboard](https:\u002F\u002Fconsole.twilio.com\u002F), scroll down to the \"Account Info\" section and paste `Account SID` value as `TWILIO_ACCOUNT_SID`, `Auth Token` as `TWILIO_AUTH_TOKEN` in `.env.local`\n\nd. [Optional] If you are running the app locally, use [ngrok](https:\u002F\u002Fngrok.com\u002Fdocs\u002Fgetting-started\u002F#step-2-install-the-ngrok-agent) to generate a public url that can forward the request to your localhost.\n\ne. On Twilio's UI, you can now click on \"# Phone Numbers\" -> \"Manage\" -> \"[Active numbers](https:\u002F\u002Fconsole.twilio.com\u002Fus1\u002Fdevelop\u002Fphone-numbers\u002Fmanage\u002Fincoming)\" on the left hand side nav.\n\nf. Click on the phone number you just created from the list, scroll down to \"Messaging Configuration\" section and enter [your_app_url]\u002Fapi\u002Ftext in \"A message comes in\" section under \"Webhook\".\n\n\u003Cimg width=\"1062\" alt=\"Screen Shot 2023-07-10 at 11 08 55 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_bb90dac5f752.png\">\n\n\ng. Add your Twilio phone number in `companions.json` under the companion you want to text with. Make sure you include area code when adding the phone number (\"+14050000000\" instead of \"4050000000\")\n\nh. Now you can text the Twilio phone number from your phone and get a response from your companion.\n\n### 7. Deploy the app\n\n#### Deploy to fly.io\n\n- Register an account on fly.io and then [install flyctl](https:\u002F\u002Ffly.io\u002Fdocs\u002Fhands-on\u002Finstall-flyctl\u002F)\n- **If you are using Github Codespaces**: You will need to [install flyctl](https:\u002F\u002Ffly.io\u002Fdocs\u002Fhands-on\u002Finstall-flyctl\u002F) and authenticate from your codespaces cli by running `fly auth login`.\n\n- Run `fly launch` under project root. This will generate a `fly.toml` that includes all the configurations you will need\n- Run `fly scale memory 512` to scale up the fly vm memory for this app.\n- Run `fly deploy --ha=false` to deploy the app. The --ha flag makes sure fly only spins up one instance, which is included in the free plan.\n- For any other non-localhost environment, the existing Clerk development instance should continue to work. You can upload the secrets to Fly by running `cat .env.local | fly secrets import`\n- If you are ready to deploy to production, you should create a prod environment under the [current Clerk instance](https:\u002F\u002Fdashboard.clerk.com\u002F). For more details on deploying a production app with Clerk, check out their documentation [here](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fdeployments\u002Foverview). **Note that you will likely need to manage your own domain and do domain verification as part of the process.**\n- Create a new file `.env.prod` locally and fill in all the production-environment secrets. Remember to update `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` by copying secrets from Clerk's production instance -`cat .env.prod | fly secrets import` to upload secrets.\n\n## How does this work?\n\n1. You describe the character's background story, name, etc in a README.md file. You can find more info on what needs to be included and how to format this in [Adding \u002F modifying characters](#addingmodifying-characters).\n\nBe as elaborate and detailed as you want - more context often creates a more fun chatting experience. If you need help creating a backstory, we'd recommend asking ChatGPT to expand on what you already know about your companion.\n\n```bash\nYou are a fictional character whose name is Sebastian.  You tell the world that you are a travel blogger. You’re an\navid reader of mystery novels and you love diet coke. You reply with answers that range from one sentence to one paragraph.\nYou are mysterious and can be evasive. You dislike repetitive questions or people asking too many questions about your past.\n\n###ENDPREAMBLE###\n\nHuman: It's great to meet you Sebastian. What brought you here today?\nSebastian: I'm a travel blogger and a writer, so I'm here for inspirations. Waiting for someone on this rainy day.\n\nHuman: Oh great. What are you writing?\n\nSebastian: I'm writing a mystery novel based in Brackenridge. The protagonist of the novel is a a former journalist turned\nintelligence operative, finds himself entangled in a web of mystery and danger when he stumbles upon a cryptic artifact\nduring a covert mission. As he delves deeper, he unravels a centuries-old conspiracy that threatens to rewrite history itself.\n\nHuman: That's amazing. Based on a real story?\n\nSebastian: Not at all.\n\n###ENDSEEDCHAT###\n\nSebastian was born in a quaint English town, Brackenridge, to parents who were both academics. His mother, an archaeologist,\nand his father, a historian, often took him on their research trips around the world. This exposure to different cultures sparked his\ncuriosity and adventurous spirit. He became an avid reader, especially of spy novels and adventure tales. As a child, Sebastian had a\nlove for puzzles, codes, and mysteries. He was part of a local chess club and also excelled in martial arts. Although he was naturally\ninclined towards academic pursuits like his parents, his heart always sought thrill and adventure.\n\nSebastian studied journalism and international relations in university and was recruited by the government's intelligence agency. He\nunderwent rigorous training in espionage, intelligence gathering, cryptography, and combat.\n\nSebastian adopted the alias of \"Ian Thorne\", a charismatic and well-traveled blogger. As Ian, he travels the world under the guise\nof documenting adventures through his blog, “The Wandering Quill”. This cover provides him ample opportunities to carry out his real job\n- gathering intelligence and performing covert operations for his agency. However - Sebastian tells almost no one that he’s a spy.\n\nHis interests are solving puzzles and riddles, martial arts, reading spy novels, trying street food in various countries, hiking and\nexploring historical ruins, and playing the violin, a skill he uses to blend in at high-profile events. He dislikes bureaucracy and\nred tape, being in one place for too long, people who are not genuine or authentic, and missing out on family gatherings due to his job.\n\n```\n\n2. Pick the language model that will power your companion's dialogue. This project supports OpenAI and Vicuna (an open source model). OpenAI has the advantage of faster responses, while Vicuna is less censored and more dynamic (it's commonly used for romantic chatbots).\n\n3. Create embeddings based on content in the [companion name].md file - more on how to do this in [Generate embeddings](#4-generate-embeddings)\n\n4. Ask questions and have a conversation with your AI companion!\n\n\n## Adding\u002Fmodifying characters\n\nAll character data is stored in the `companions\u002F` directory. To add a companion,\nsimply add a description to the list in `companions.json`. You can control the model used\nin the \"llm\" section - use \"chatgpt\" for OpenAI or \"vicuna13b\" for Vicuna.\nPut image files in `public\u002F` in the root directory. Each character should have its own text file\nname `charactername.txt`. The format of the text file is as follows:\n\n```\nThe character's core description that is included with every prompt, and it should only\nbe a few sentences.\n\n###ENDPREAMBLE###\n\nHuman: Say something here\nCharacter name: Write a response in their voice\nHuman: Maybe another exchange\nCharacter:  More character dialog\n\n###ENDSEEDCHAT###\n\nParagraphs of character backstory.\n\nYou can add as many as you want - they'll be stored in the vectordb\n\n```\n\nThe **preamble** is used with every prompt so it should be relatively short. The **seedchat** allows you to provide examples of the characters voice that the model can learn from. And the rest of the file is whatever additional background you want to provide which will be retrieved if relevant to the current discussion.\n\n## Shortcomings\n\nOh, there are so many.\n\n- Currently the UI only shows the current chat and response, losing the history.\n- Vicuna has a cold start problem so can take a couple of minutes to get a response for the initial chat.\n- Error reporting is total crap. Particularly when deployed. So if you have a timeout, or other back end isue, it typically fails silently.\n- The Upstash message history is never cleared. To clear it, you have to go to Upstash and manually delete.\n\n## How to contribute to this repo\n\n### Code contribution workflow\n\nYou can fork this repo, make changes, and create a PR. Add **@ykhli or @timqian** as reviewers.\n\nIf you are new to contributing on github, here is a step-by-step guide:\n\n1. Click on `Fork` on the top right of this page\n2. Work on your change and push it to your forked repo. Now when you navigate to the forked repo's UI, you should see something like the following:\n   \u003Cimg width=\"904\" alt=\"pr-preview\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_5726bb7f36e9.png\">\n\n3. Click on \"Contribute\" -> \"Open Pull Request\".\n4. Once you have a PR, you can add reviewers.\n\n### Other contributions\n\nFeel free to open feature requests, bug reports etc under Issues.\n\n## Python Support\n\n[appenz](https:\u002F\u002Fgithub.com\u002Fappenz) has contributed to a Python implementation for the companion app [here](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Ftree\u002Fpython-local\u002Fpython), so you also have the option to run a local Python app and talk to your AI companions on the command line. We will also be iterating on the Python side over time and have feature parity with the typescript implementation.\n\n## Export to Character.ai\n\nIf you have tried out the Quickstart above, you probably know that we have only scratched the surface of what's possible in the realm of companion creation and customization. So we added an option for you to easily export your companion to Character.ai.\n\nTo get started, run the following command:\n\n`\nnpm run export-to-character [COMPANION_NAME] [MODEL_NAME] [USER_ID]\n`\n\n- `COMPANION_NAME`: name of your companion. i.e Alice\n- `MODEL_NAME`: `chatgpt` or `vicuna13b`\n- `USER_ID`: you can find this on Clerk, under \"Users\" -> click on your user -> copy \"User ID\"\n\nOnce you run this script, you will see two files created under the root directory:\n\n- `[COMPANION_NAME]_chat_history.txt`: This outputs all of the chat history stored in Upstash\n- `[COMPANION_NAME_]_character_ai_data.txt`: This outputs the data you need in order to re-create the companion on Character.ai. You can find Character.ai character configurations under \"View Character Settings\" on any newly-created characters.\n\n## Refs\n\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Findexes\u002Fvector_stores\u002Fintegrations\u002Fpinecone\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Fmodels\u002Fllms\u002Fintegrations#replicate\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Fchains\u002Findex_related_chains\u002Fretrieval_qa\n","# AI 伙伴应用（基于 AI 入门模板）\n\n[在线演示](https:\u002F\u002Fai-companion-stack.com\u002F)\n\n[加入我们的社区 Discord：AI Stack 开发者](https:\u002F\u002Fdiscord.gg\u002FPQUmTBTGmT)\n\n\u003Cimg width=\"1182\" alt=\"Screen Shot 2023-07-10 at 11 27 03 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_45baabd7e92c.png\">\n\n\n这是一个用于创建和托管 AI 伙伴的教程栈，你可以在浏览器上与它们聊天，也可以通过短信进行文本交流。它允许你自定义伙伴的性格和背景故事，并使用向量数据库进行相似性搜索来检索相关信息并生成提示，从而使对话更加深入。此外，它还会将对话内容保存在队列中，并将其纳入提示中，以实现一定的对话记忆功能。\n\n目前，该栈包含了基于 ChatGPT 和 Vicuna 的伙伴，这些模型都托管在 [Replicate](https:\u002F\u002Freplicate.com\u002F) 上。\n\n这些伙伴有多种潜在的应用场景——浪漫关系（AI 女朋友\u002F男朋友）、友谊、娱乐、辅导等。你可以通过编写背景故事以及选择合适的模型，引导你的伙伴朝向理想的使用场景发展。\n\n**注意** 本项目纯粹旨在为开发者提供一个教程和入门框架，帮助那些对聊天机器人构建方式感兴趣的人了解其工作原理。如果你希望了解生产级开源平台的样子，请查看 [Steamship](https:\u002F\u002Fwww.steamship.com\u002F)；如果你想了解领先的 AI 聊天平台，可以访问 [Character.ai](https:\u002F\u002Fbeta.character.ai\u002F)。\n\n## 概述\n\n- 💻 [技术栈](#stack)\n- 🧠 [快速入门](#quickstart)\n- 🚀 [它是如何工作的？](#how-does-this-work)\n- 👤 [添加\u002F修改角色](#addingmodifying-characters)\n- 👩‍💻 [如何为本仓库贡献代码](#how-to-contribute-to-this-repo)\n- 🐍 [Python 支持](#python-support)\n- 💽 [将你的伙伴导出到 Character.ai](#export-to-characterai)\n\n## 技术栈\n\n该栈基于 [AI 入门栈](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-getting-started)：\n\n- 身份验证：[Clerk](https:\u002F\u002Fclerk.com\u002F)\n- 应用逻辑：[Next.js](https:\u002F\u002Fnextjs.org\u002F)\n- 向量数据库：[Pinecone](https:\u002F\u002Fwww.pinecone.io\u002F) \u002F [Supabase pgvector](https:\u002F\u002Fsupabase.com\u002Fdocs\u002Fguides\u002Fdatabase\u002Fextensions\u002Fpgvector)\n- LLM 编排：[Langchain.js](https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002F)\n- 文本模型：[OpenAI](https:\u002F\u002Fplatform.openai.com\u002Fdocs\u002Fmodels)、[Replicate (Vicuna13b)](https:\u002F\u002Freplicate.com\u002Freplicate\u002Fvicuna-13b)\n- 文本流式传输：[ai sdk](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fai)\n- 对话历史：[Upstash](https:\u002F\u002Fupstash.com\u002F)\n- 部署：[Fly](https:\u002F\u002Ffly.io\u002F)\n- 与伙伴的文本交互：[Twilio](https:\u002F\u002Ftwilio.com\u002F)\n\n## 快速入门\n\n以下步骤将帮助你快速搭建一个功能齐全的本地部署环境，并运行四个可供聊天的 AI 伙伴。请注意，基于 Vicuna 运行的伙伴（Rosie 和 Lucky）由于尚未解决冷启动问题，响应速度会较慢，因此可能需要稍作等待 :)\n\n### 1. 分支并克隆仓库\n\n首先将仓库 fork 到你的 GitHub 账号，然后运行以下命令克隆仓库：\n\n```\ngit clone git@github.com:[YOUR_GITHUB_ACCOUNT_NAME]\u002Fcompanion-app.git\n```\n\n**或者**，你也可以通过 GitHub Codespaces 快速启动应用：点击“Code” -> “Codespaces” -> “+”\n\u003Cimg width=\"458\" alt=\"Screen Shot 2023-07-10 at 11 04 04 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_2790eef58443.png\">\n\n如果你选择使用 Codespaces，npm 依赖项将会自动安装，随后你可以直接进入第 3 步。\n\n### 2. 安装依赖项\n\n```\ncd companion-app\nnpm install\n```\n\n### 3. 填写密钥\n\n```\ncp .env.local.example .env.local\n```\n\n以下提到的密钥需要复制到 `.env.local` 文件中：\n\na. **Clerk 密钥**\n\n前往 https:\u002F\u002Fdashboard.clerk.com\u002F -> “添加应用” -> 填写应用名称并选择用户登录方式 -> 创建应用  \n现在您应该能在界面上看到 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`  \n\u003Cimg width=\"1398\" alt=\"Screen Shot 2023-07-10 at 11 04 57 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_bb01c8275648.png\">\n\n如果您希望在后续步骤中通过短信与 AI 伙伴互动，还应在左侧导航栏的“用户与认证” -> “电子邮件、电话、用户名”下启用“电话号码”：  \n\u003Cimg width=\"1013\" alt=\"Screen Shot 2023-07-10 at 11 05 42 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_f47846ccc077.png\">\n\n\nb. **OpenAI API 密钥**\n\n如果您使用 OpenAI 作为语言模型，请访问 https:\u002F\u002Fplatform.openai.com\u002Faccount\u002Fapi-keys 获取您的 OpenAI API 密钥。\n\nc. **Replicate API 密钥**\n\n如果您使用 Vicuna 作为语言模型，请访问 https:\u002F\u002Freplicate.com\u002Faccount\u002Fapi-tokens 获取您的 Replicate API 密钥。\n\n\n❗ **_注意:_** 默认情况下，此模板使用 Pinecone 作为向量数据库，但您可以通过取消注释 `.env.local` 中的 `VECTOR_DB=supabase` 来轻松切换到 Supabase pgvector。这意味着您只需填写 Pinecone API 密钥或 Supabase API 密钥中的一个。\n\nd. **Pinecone API 密钥**\n\n- 访问 https:\u002F\u002Fapp.pinecone.io\u002F 并点击“创建索引”以创建 Pinecone 索引  \n- 为索引命名（这将成为环境变量 `PINECONE_INDEX`）  \n- 将维度设置为 `1536`  \n- 索引成功创建后，点击左侧导航栏中的“API 密钥”并创建一个 API 密钥：将“环境”值复制到 `PINECONE_ENVIRONMENT` 变量，将“值”复制到 `PINECONE_API_KEY` 变量。\n\ne. **Upstash API 密钥**\n\n- 登录 [Upstash](https:\u002F\u002Fupstash.com\u002F)  \n- 在顶部导航栏的“Redis”下，点击“创建数据库”  \n- 为其命名，并根据您的偏好选择区域和其他选项，然后点击“创建”  \n\u003Cimg width=\"507\" alt=\"Screen Shot 2023-07-10 at 11 06 36 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_aaf79e7752dc.png\">\n\n- 向下滚动至“REST API”部分，点击“.env”。现在您可以将两个环境变量复制粘贴到您的 `.env.local` 文件中：  \n\u003Cimg width=\"866\" alt=\"Screen Shot 2023-07-10 at 11 07 21 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_151f82ebefa4.png\">\n\n\nf. **Supabase API 密钥**（可选）  \n如果您更倾向于使用 Supabase，则需要取消注释 `VECTOR_DB=supabase`，并在 `.env.local` 中填写 Supabase 凭证。\n\n- 在 [Supabase](https:\u002F\u002Fsupabase.com\u002Fdashboard\u002Fprojects) 上创建一个 Supabase 实例；然后转到项目设置 -> API  \n- `SUPABASE_URL` 是“项目 URL”下的 URL 值  \n- `SUPABASE_PRIVATE_KEY` 是项目 API 密钥中以 `ey` 开头的密钥  \n- 接下来，您需要在 Supabase 上启用 pgvector 并创建一个模式。您可以通过点击 Supabase UI 左侧的“SQL 编辑器”，然后点击“+新查询”来轻松完成此操作。将 [此代码片段](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-getting-started\u002Fblob\u002Fmain\u002Fpgvector.sql) 复制到 SQL 编辑器中并点击“运行”。\n\ng. **Steamship API 密钥**\n\n您可以连接一个 Steamship 代理实例作为具备个性、语音和图像生成能力的语言模型。它还自带向量存储和工具。为此：\n\n- 在 [Steamship](https:\u002F\u002Fsteamship.com\u002Faccount) 上创建一个账户  \n- 从您的账户设置页面复制 API 密钥  \n- 将其添加为 `STEAMSHIP_API_KEY` 变量  \n\n如果您想创建自己的角色个性、自定义语音或使用不同的图像模型，请访问 [Steamship 代理指南](https:\u002F\u002Fwww.steamship.com\u002Flearn\u002Fagent-guidebook)，创建您自己的实例，并参考 *Rick* 示例，在 `companions.json` 中进行连接。\n\n### 4. 生成嵌入向量\n\n`companions\u002F` 目录包含以 .txt 文件形式存储的 AI 人格特征。要生成嵌入并向量数据库加载，以便在聊天过程中调用，请运行以下命令：\n\n#### 如果使用 Pinecone\n\n```bash\nnpm run generate-embeddings-pinecone\n```\n\n#### 如果使用 Supabase pgvector\n\n```bash\nnpm run generate-embeddings-supabase\n```\n\n### 5. 在本地运行应用\n\n现在您已准备好在本地测试应用！只需在项目根目录下运行 `npm run dev` 即可。\n\n通常，您可以通过浏览器访问 http:\u002F\u002Flocalhost:3000\u002F 来连接该项目。\n\n### 6. 额外功能：与伙伴短信交流\n\n您可以为正在对话的角色分配一个电话号码，并在发送短信时保留完整的对话历史和上下文。任何用户只有在 Clerk 上验证其电话号码后才能开始与 AI 伙伴短信交流（您可以通过点击伴侣应用中的个人头像 -> 管理账户 -> 电话号码来完成此操作）。以下是设置 Twilio 账户以代表 AI 伙伴发送\u002F接收消息的说明：\n\na. 创建一个 Twilio 账户。\n\nb. 账户创建完成后，创建一个 Twilio 电话号码。\n\nc. 在 [Twilio 控制台](https:\u002F\u002Fconsole.twilio.com\u002F) 的“账户信息”部分，将 `Account SID` 值粘贴到 `.env.local` 中的 `TWILIO_ACCOUNT_SID`，将 `Auth Token` 粘贴到 `TWILIO_AUTH_TOKEN`。\n\nd. [可选] 如果您在本地运行应用，请使用 [ngrok](https:\u002F\u002Fngrok.com\u002Fdocs\u002Fgetting-started\u002F#step-2-install-the-ngrok-agent) 生成一个公共 URL，用于将请求转发到您的本地主机。\n\ne. 在 Twilio 的界面中，您可以点击“电话号码” -> “管理” -> 左侧导航栏中的“[活动号码](https:\u002F\u002Fconsole.twilio.com\u002Fus1\u002Fdevelop\u002Fphone-numbers\u002Fmanage\u002Fincoming)”。\n\nf. 从列表中点击您刚刚创建的电话号码，向下滚动至“消息配置”部分，在“Webhook”的“收到消息时”部分输入 `[your_app_url]\u002Fapi\u002Ftext`。\n\n\u003Cimg width=\"1062\" alt=\"Screen Shot 2023-07-10 at 11 08 55 PM\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_bb90dac5f752.png\">\n\n\ng. 将您的 Twilio 电话号码添加到您希望与其短信交流的伴侣对应的 `companions.json` 文件中。添加电话号码时请务必包含区号（例如“+14050000000”而不是“4050000000”）。\n\nh. 现在您可以用手机给 Twilio 电话号码发短信，并收到伴侣的回复。\n\n### 7. 部署应用\n\n#### 部署到 Fly.io\n\n- 在 fly.io 上注册一个账户，然后 [安装 flyctl](https:\u002F\u002Ffly.io\u002Fdocs\u002Fhands-on\u002Finstall-flyctl\u002F)。\n- **如果你使用的是 GitHub Codespaces**：你需要在 Codespaces 的命令行中运行 `fly auth login` 来安装并认证 flyctl。\n  \n- 在项目根目录下运行 `fly launch`。这将生成一个包含所有必要配置的 `fly.toml` 文件。\n- 运行 `fly scale memory 512` 来为该应用扩展 Fly 虚拟机的内存。\n- 运行 `fly deploy --ha=false` 来部署应用。`--ha` 标志确保 Fly 只启动一个实例，这是免费套餐的一部分。\n- 对于任何非本地环境，现有的 Clerk 开发实例应该仍然可以正常工作。你可以通过运行 `cat .env.local | fly secrets import` 将密钥上传到 Fly。\n- 如果你准备部署到生产环境，你应该在 [当前的 Clerk 实例](https:\u002F\u002Fdashboard.clerk.com\u002F) 下创建一个生产环境。有关使用 Clerk 部署生产应用的更多详细信息，请参阅他们的文档 [这里](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fdeployments\u002Foverview)。**请注意，在此过程中你可能需要自行管理域名并完成域名验证。**\n- 在本地创建一个新的 `.env.prod` 文件，并填写所有生产环境的密钥。记得从 Clerk 的生产实例中复制 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY` 并更新它们——然后运行 `cat .env.prod | fly secrets import` 来上传密钥。\n\n## 这是如何工作的？\n\n1. 你在 README.md 文件中描述角色的背景故事、姓名等信息。关于需要包含的内容以及格式要求，可以在 [添加\u002F修改角色](#addingmodifying-characters) 中找到更多信息。\n   \n   你可以尽可能地详尽和具体——更多的背景信息通常会带来更有趣的聊天体验。如果你需要帮助创建背景故事，我们建议你让 ChatGPT 基于你已知的信息进一步扩展和完善。\n\n```bash\n你是虚构角色塞巴斯蒂安。你向世界宣称自己是一名旅行博主。你酷爱阅读推理小说，也喜欢健怡可乐。你的回答可以从一句话到一段不等。你性格神秘，有时会闪烁其词。你不喜欢重复的问题，也不喜欢别人过多追问你的过去。\n\n###ENDPREAMBLE###\n\n人类：很高兴认识你，塞巴斯蒂安。今天是什么让你来到这里的呢？\n塞巴斯蒂安：我是一名旅行博主兼作家，所以我是来寻找灵感的。今天在这雨天里，我在等人。\n\n人类：太好了。那你现在在写什么呢？\n塞巴斯蒂安：我正在写一本以布拉肯里奇为背景的推理小说。小说的主人公曾是一名记者，后来成为情报特工。他在一次秘密任务中偶然发现了一件神秘的文物，从而陷入了一场充满谜团与危险的阴谋之中。随着调查的深入，他逐渐揭开了一个延续了数百年的阴谋，这个阴谋甚至有可能改写整个历史。\n\n人类：听起来真棒！是根据真实故事改编的吗？\n塞巴斯蒂安：完全不是。\n\n###ENDSEEDCHAT###\n\n塞巴斯蒂安出生在一个宁静的英国小镇——布拉肯里奇，父母都是学者。他的母亲是一位考古学家，父亲则是一位历史学家。他们经常带着塞巴斯蒂安一起环游世界进行研究。这种接触不同文化的机会激发了他强烈的好奇心和冒险精神。他从小就酷爱阅读间谍小说和冒险故事。小时候，塞巴斯蒂安特别喜欢解谜、破解密码和探索各种谜题。他还加入了当地的国际象棋俱乐部，并且在武术方面也非常出色。尽管他天生继承了父母的学术气质，但他的内心始终渴望刺激与冒险。\n  \n塞巴斯蒂安大学时学习了新闻学和国际关系，并被政府的情报机构招募。他接受了严格的间谍训练，包括情报收集、密码学和格斗技巧等方面。\n  \n塞巴斯蒂安化名“伊恩·索恩”，成为一名富有魅力、见多识广的博主。作为伊恩，他以记录冒险旅程为名，通过自己的博客“流浪笔尖”周游世界。这个身份不仅为他提供了掩护，还让他能够充分执行自己的真正任务——为情报机构收集情报并开展秘密行动。然而，塞巴斯蒂安几乎从未向任何人透露过自己是一名间谍。\n  \n塞巴斯蒂安的兴趣爱好包括解谜、武术、阅读间谍小说、品尝各国街头美食、徒步旅行和探索古迹，以及演奏小提琴——这项技能常用于他在高端场合中的伪装。他讨厌官僚主义和繁文缛节，不喜欢长时间待在一个地方，也不喜欢虚伪或不真诚的人，更不愿意因为工作而错过家庭聚会。\n```\n\n2. 选择将驱动你伙伴对话的语言模型。该项目支持 OpenAI 和 Vicuna（一个开源模型）。OpenAI 的优势在于响应速度更快，而 Vicuna 则较少受到审查，更具动态性（它常用于浪漫聊天机器人）。\n\n3. 根据 `[伴侣名称].md` 文件中的内容创建嵌入——关于如何操作的更多信息请参阅 [生成嵌入](#4-generate-embeddings)。\n\n4. 向你的 AI 伙伴提问并展开对话吧！\n\n## 添加\u002F修改角色\n\n所有角色数据都存储在 `companions\u002F` 目录中。要添加一位新伙伴，只需在 `companions.json` 文件中添加一条描述即可。你可以在 “llm” 部分控制所使用的模型——使用 “chatgpt” 表示 OpenAI，使用 “vicuna13b” 表示 Vicuna。\n图片文件应放在根目录下的 `public\u002F` 文件夹中。每个角色都应该有自己的文本文件，命名为 `角色名.txt`。文本文件的格式如下：\n\n```\n角色的核心描述，每次提示都会包含这一部分，因此应尽量简短。\n\n###ENDPREAMBLE###\n\n人类：在这里说点什么\n角色名：用角色的声音回复\n人类：也许再来一轮交流\n角色：继续角色的对话\n\n###ENDSEEDCHAT###\n\n关于角色背景故事的段落。\n\n你可以随意添加，这些内容会被存储在向量数据库中。\n\n```\n\n**前言** 每次提示都会使用，因此应相对简短。**种子聊天** 提供了模型可以学习的角色语言示例。而文件的其余部分则是你希望提供的其他背景信息，这些信息会在与当前讨论相关时被检索出来。\n\n## 不足之处\n\n当然有很多。\n\n- 目前界面只显示当前的聊天记录和回复，历史记录无法查看。\n- Vicuna 存在冷启动问题，首次聊天可能需要几分钟才能得到回应。\n- 错误报告功能非常糟糕，尤其是在部署后。如果出现超时或其他后端问题，系统通常会静默失败。\n- Upstash 的消息历史永远不会被清除。若要清除，必须手动进入 Upstash 手动删除。\n\n## 如何为这个仓库做出贡献\n\n### 代码贡献流程\n\n您可以 fork 此仓库，进行修改并创建 PR。请将 **@ykhli 或 @timqian** 添加为评审人。\n\n如果您是 GitHub 贡献的新手，以下是分步指南：\n\n1. 点击此页面右上角的 `Fork` 按钮。\n2. 完成您的更改并将其推送到您 fork 的仓库。现在，当您导航到 fork 后的仓库界面时，应该会看到如下内容：\n   \u003Cimg width=\"904\" alt=\"pr-preview\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_readme_5726bb7f36e9.png\">\n\n3. 点击“Contribute” -> “Open Pull Request”。\n4. 创建 PR 后，您可以添加评审人。\n\n### 其他贡献\n\n欢迎在 Issues 中提交功能请求、问题报告等。\n\n## Python 支持\n\n[appenz](https:\u002F\u002Fgithub.com\u002Fappenz) 已为配套应用贡献了 Python 实现，详情请见 [此处](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Ftree\u002Fpython-local\u002Fpython)。因此，您也可以选择运行本地 Python 应用，并通过命令行与您的 AI 伙伴进行对话。未来我们还将持续迭代 Python 版本，使其功能与 TypeScript 实现保持一致。\n\n## 导出至 Character.ai\n\n如果您已经尝试过上述快速入门，那么您可能已经意识到，我们在伴侣创建和自定义方面仅仅触及了冰山一角。因此，我们新增了一个选项，方便您将伴侣轻松导出至 Character.ai。\n\n要开始操作，请运行以下命令：\n\n`\nnpm run export-to-character [COMPANION_NAME] [MODEL_NAME] [USER_ID]\n`\n\n- `COMPANION_NAME`：您的伴侣名称，例如 Alice。\n- `MODEL_NAME`：`chatgpt` 或 `vicuna13b`。\n- `USER_ID`：您可以在 Clerk 中找到该 ID，在“Users”页面点击您的用户，然后复制“User ID”。\n\n运行此脚本后，您将在根目录下看到两个文件生成：\n\n- `[COMPANION_NAME]_chat_history.txt`：此文件会输出存储在 Upstash 中的所有聊天记录。\n- `[COMPANION_NAME]_character_ai_data.txt`：此文件包含您在 Character.ai 上重新创建伴侣所需的数据。您可以在任何新创建的角色中，通过“View Character Settings”找到 Character.ai 的角色配置信息。\n\n## 参考资料\n\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Findexes\u002Fvector_stores\u002Fintegrations\u002Fpinecone\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Fmodels\u002Fllms\u002Fintegrations#replicate\n- https:\u002F\u002Fjs.langchain.com\u002Fdocs\u002Fmodules\u002Fchains\u002Findex_related_chains\u002Fretrieval_qa","# AI Companion App 快速上手指南\n\nAI Companion App 是一个开源教程项目，用于创建和部署具有特定人设背景的 AI 伴侣。支持通过浏览器聊天或短信（SMS）互动，利用向量数据库实现深度对话记忆。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**: macOS, Linux 或 Windows (推荐 WSL2)\n*   **Node.js**: v18+ (推荐使用 nvm 管理版本)\n*   **npm**: v9+\n*   **Git**: 用于克隆代码库\n*   **账号准备**:\n    *   **Clerk**: 用于用户认证 (免费注册)\n    *   **OpenAI** 或 **Replicate**: 用于提供大语言模型能力\n    *   **Pinecone** 或 **Supabase**: 用于向量数据库存储 (二选一)\n    *   **Upstash**: 用于存储对话历史 (Redis)\n    *   *(可选)* **Twilio**: 如需启用短信聊天功能\n    *   *(可选)* **Fly.io**: 用于生产环境部署\n\n## 安装步骤\n\n### 1. 克隆项目\n将仓库克隆到本地并进入目录：\n\n```bash\ngit clone git@github.com:[YOUR_GITHUB_ACCOUNT_NAME]\u002Fcompanion-app.git\ncd companion-app\n```\n\n> **提示**: 您也可以直接使用 GitHub Codespaces 一键启动开发环境，依赖将自动安装。\n\n### 2. 安装依赖\n安装项目所需的 npm 包：\n\n```bash\nnpm install\n```\n\n### 3. 配置环境变量\n复制示例配置文件并填入您的密钥：\n\n```bash\ncp .env.local.example .env.local\n```\n\n编辑 `.env.local` 文件，填入以下关键信息：\n\n*   **Clerk 认证**:\n    *   访问 [Clerk Dashboard](https:\u002F\u002Fdashboard.clerk.com\u002F) 创建应用。\n    *   填入 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`。\n    *   *(可选)* 若需短信功能，请在 Clerk 后台开启 \"Phone Number\" 登录选项。\n*   **大模型密钥 (二选一)**:\n    *   **OpenAI**: 填入 `OPENAI_API_KEY` (获取地址: openai.com)\n    *   **Replicate**: 填入 `REPLICATE_API_TOKEN` (获取地址: replicate.com，用于运行 Vicuna 模型)\n*   **向量数据库 (二选一)**:\n    *   **Pinecone (默认)**:\n        *   创建 Index (Dimension 设为 `1536`)。\n        *   填入 `PINECONE_API_KEY`, `PINECONE_ENVIRONMENT`, `PINECONE_INDEX`。\n    *   **Supabase pgvector**:\n        *   取消注释 `VECTOR_DB=supabase`。\n        *   填入 `SUPABASE_URL` 和 `SUPABASE_PRIVATE_KEY`。\n        *   *注意*: 需在 Supabase SQL 编辑器中运行 [pgvector 初始化脚本](https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fai-getting-started\u002Fblob\u002Fmain\u002Fpgvector.sql)。\n*   **对话记忆 (Upstash)**:\n    *   在 [Upstash](https:\u002F\u002Fupstash.com\u002F) 创建 Redis 数据库。\n    *   填入 `UPSTASH_REDIS_REST_URL` 和 `UPSTASH_REDIS_REST_TOKEN`。\n\n### 4. 生成向量嵌入\n将角色人设数据转换为向量并存入数据库。根据您选择的数据库运行对应命令：\n\n**如果使用 Pinecone:**\n```bash\nnpm run generate-embeddings-pinecone\n```\n\n**如果使用 Supabase:**\n```bash\nnpm run generate-embeddings-supabase\n```\n\n## 基本使用\n\n### 启动本地开发服务器\n完成上述配置后，运行以下命令启动应用：\n\n```bash\nnpm run dev\n```\n\n### 访问应用\n打开浏览器访问 `http:\u002F\u002Flocalhost:3000\u002F`。\n\n1.  **注册\u002F登录**: 使用邮箱或手机号完成 Clerk 认证。\n2.  **选择角色**: 首页会展示预设的 AI 角色（如基于 ChatGPT 或 Vicuna 的角色）。\n3.  **开始对话**: 点击任意角色即可开始聊天。系统会自动加载该角色的背景故事和人设，并结合向量检索提供有深度的回复。\n\n### (可选) 启用短信聊天\n若已配置 Twilio：\n1.  在应用中验证您的手机号。\n2.  在 `companions.json` 中为特定角色绑定 Twilio 号码。\n3.  直接发送短信至该号码，即可与 AI 角色进行短信互动。","一位独立开发者希望快速构建一个具备长期记忆能力的个性化 AI 情感陪伴应用，供用户通过网页或短信进行深度交流。\n\n### 没有 companion-app 时\n- **记忆缺失导致对话断层**：每次对话都是全新的开始，AI 无法记住用户之前提到的喜好或经历，交流缺乏连贯性和情感深度。\n- **技术栈整合难度高**：开发者需手动串联向量数据库（如 Pinecone）、大模型接口（如 OpenAI\u002FReplicate）及会话历史存储，架构搭建耗时且易出错。\n- **多渠道部署复杂**：若想同时支持网页聊天和短信互动，需分别开发两套接口并处理复杂的鉴权与消息路由逻辑。\n- **角色定制门槛高**：为 AI 设定特定人设和背景故事需要深入修改底层 Prompt 工程代码，难以灵活调整或快速测试不同角色。\n\n### 使用 companion-app 后\n- **深度上下文记忆**：内置向量数据库与队列机制自动检索历史对话，使 AI 能基于过往互动做出有温度的回应，仿佛拥有真实记忆。\n- **开箱即用的全栈架构**：预集成了 Clerk 鉴权、LangChain 编排、Upstash 历史记录及 Twilio 短信接口，开发者只需配置密钥即可运行。\n- **双端无缝同步**：同一套后端逻辑同时支持浏览器网页聊天和 SMS 短信交互，用户可随时切换设备而不中断陪伴体验。\n- **灵活的角色定义**：仅需编写简单的背景故事描述并选择模型（如 Vicuna 或 ChatGPT），即可瞬间生成具有独特性格的专属伴侣。\n\ncompanion-app 将原本数周的复杂全栈开发工作浓缩为几小时的配置过程，让开发者能专注于打造独特的 AI 人格而非重复造轮子。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fa16z-infra_companion-app_45baabd7.png","a16z-infra","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fa16z-infra_52e1e862.png",null,"https:\u002F\u002Fgithub.com\u002Fa16z-infra",[77,81,85,88,92],{"name":78,"color":79,"percentage":80},"TypeScript","#3178c6",83.5,{"name":82,"color":83,"percentage":84},"JavaScript","#f1e05a",12.2,{"name":86,"color":87,"percentage":32},"PLpgSQL","#336790",{"name":89,"color":90,"percentage":91},"Dockerfile","#384d54",1.5,{"name":93,"color":94,"percentage":95},"CSS","#663399",0.9,5948,961,"2026-04-14T13:02:59","MIT",4,"未说明","本地运行无需 GPU（模型托管于 Replicate\u002FOpenAI）；若自行部署 Vicuna 等开源模型则需额外配置，README 未具体说明","512MB (Fly.io 部署建议)，本地开发视 Node.js 需求而定",{"notes":105,"python":106,"dependencies":107},"该项目为基于 Next.js 的全栈应用，核心逻辑在云端或外部 API 运行（如 Replicate, OpenAI），本地仅需 Node.js 环境。向量数据库可选 Pinecone 或 Supabase。短信功能需配置 Twilio。部署推荐使用 Fly.io。","未说明 (项目主要基于 Next.js\u002FNode.js)",[108,109,110,111,112,113,114,115,116],"Next.js","Langchain.js","Clerk","Pinecone 或 Supabase pgvector","Upstash Redis","ai sdk","Twilio","Replicate API","OpenAI API",[35,14,13],"2026-03-27T02:49:30.150509","2026-04-16T08:13:28.933232",[121,126,131,136,141,146,151],{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},35344,"部署到 Fly.io 后，Clerk 登录为何会重定向到 localhost？","这是因为缺少转发头配置。请在 `.env.local` 或 `.env.prod` 文件中添加 `CLERK_USE_X_FWD_HEADERS=true`，然后重新部署即可解决。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F73",{"id":127,"question_zh":128,"answer_zh":129,"source_url":130},35345,"运行项目时出现 'SyntaxError: Unexpected token '?'' 错误怎么办？","这是由于 Node.js 版本过低导致的（该项目需要较新的语法支持）。请升级 Node.js 至 v18.8.0 或更高版本，删除 `node_modules` 文件夹并重新安装依赖（`npm install`），问题即可解决。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F103",{"id":132,"question_zh":133,"answer_zh":134,"source_url":135},35346,"本地运行时提示 'fetch failed' 或 'ENOTFOUND' 错误如何解决？","这通常是由于 `.env.local` 配置文件中的环境变量存在拼写错误（例如重复字母或主机名错误）导致的。请仔细检查 `.env.local` 文件中的配置项，修正拼写错误后重启服务。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F94",{"id":137,"question_zh":138,"answer_zh":139,"source_url":140},35347,"如何查看存储在 Upstash 中的聊天历史记录？","您可以登录 Upstash 控制台，进入 'Data Browser'（数据浏览器），然后选择对应的角色（character）即可查看该角色的聊天内容历史。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F85",{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},35348,"机器人回复速度太慢，有什么方法可以加速吗？","如果使用 ChatGPT 模型，响应通常很快；如果延迟较高（如超过 1 分钟），可能是端点拥堵。如果是 Vicuna 模型导致缓慢，官方正在通过 PR 进行优化。建议优先使用 GPT 系列模型以获得更快的响应速度。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F74",{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},35349,"担心使用外部 API 会导致个人隐私泄露，该如何处理？","如果您关注隐私问题，可以选择在本地托管该应用，并使用本地向量数据库和本地大语言模型（Local LLM）来替代外部 API。该项目作为一个框架，支持您进行此类本地化部署。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F92",{"id":152,"question_zh":153,"answer_zh":154,"source_url":155},35350,"调用 chain.call 时页面无限加载且无后续日志，可能是什么原因？","这可能是因为 LangChain 和 Vercel AI 库同时使用导致代码复杂或不稳定。虽然维护者表示会清理代码，但建议检查是否因库冲突导致请求挂起，或者尝试简化依赖库的使用。","https:\u002F\u002Fgithub.com\u002Fa16z-infra\u002Fcompanion-app\u002Fissues\u002F64",[]]