{"id":24975116,"url":"https://github.com/jeffersonqin/typexo-cli","last_synced_at":"2025-04-11T11:51:21.931Z","repository":{"id":108622534,"uuid":"366727809","full_name":"JeffersonQin/typexo-cli","owner":"JeffersonQin","description":"📝 A Hexo-like cli tool for Typecho Blogs, used for blog writing.","archived":false,"fork":false,"pushed_at":"2024-05-13T18:20:13.000Z","size":97,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T08:11:13.867Z","etag":null,"topics":["blog","cli","fastapi","hexo","hexo-blog","python","typecho"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JeffersonQin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-12T13:36:50.000Z","updated_at":"2024-05-28T09:45:59.000Z","dependencies_parsed_at":"2023-03-25T20:34:30.404Z","dependency_job_id":null,"html_url":"https://github.com/JeffersonQin/typexo-cli","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffersonQin%2Ftypexo-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffersonQin%2Ftypexo-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffersonQin%2Ftypexo-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffersonQin%2Ftypexo-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeffersonQin","download_url":"https://codeload.github.com/JeffersonQin/typexo-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248390253,"owners_count":21095751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blog","cli","fastapi","hexo","hexo-blog","python","typecho"],"created_at":"2025-02-03T20:44:40.715Z","updated_at":"2025-04-11T11:51:21.905Z","avatar_url":"https://github.com/JeffersonQin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 介绍\r\n\r\n受到`Hexo`这样的基于`nodejs`的，可以本地编辑的博客的启发，`typexo`旨在对于`typecho`的博客开发类似的功能。本项目`typexo-cli`是本地端的实现，用于编辑内容、本地测试、远程部署。\r\n\r\n**目前本项目仅针对`MySQL`数据库进行开发，其他数据库日后会进行支持。**\r\n\r\n**目前本项目不支持`typecho`的`attachments`, 解决方案是使用自己的图床, 该功能可能会在日后支持（可能性不大）。**\r\n\r\n**请注意：服务端程序会直接对数据库进行操作，如果你不知道程序在干什么，请勿执行。硬盘有价，数据无价。请确保在操作之前对数据库进行备份。**\r\n\r\n- [介绍](#介绍)\r\n- [环境及依赖项](#环境及依赖项)\r\n- [术语](#术语)\r\n- [原理以及流程](#原理以及流程)\r\n- [准备就绪，开始！](#准备就绪开始)\r\n\t- [在服务器搭好`typexo-server`](#在服务器搭好typexo-server)\r\n\t- [配置`config.yml`](#配置configyml)\r\n\t- [Quick Start](#quick-start)\r\n- [关于本地测试服务器](#关于本地测试服务器)\r\n- [命令说明](#命令说明)\r\n\t- [✅ `init`](#-init)\r\n\t- [✅ `rm`](#-rm)\r\n\t- [✅ `commit`](#-commit)\r\n\t- [✅ `discard-change`](#-discard-change)\r\n\t- [✅ `status`](#-status)\r\n\t- [✅ `merge {prod|test}`](#-merge-prodtest)\r\n\t- [✅ `fix-git-utf8`](#-fix-git-utf8)\r\n\t- [✅ `prod-test`](#-prod-test)\r\n\t- [✅ `clone`](#-clone)\r\n\t- [✅ `pull {prod|test}`](#-pull-prodtest)\r\n\t- [✅ `push`](#-push)\r\n\t- [✅ `format`](#-format)\r\n\t- [✅ `new [--draft] {post|page} TITLE`](#-new---draft-postpage-title)\r\n\t- [✅ `import [--draft] {post|page} FILE`](#-import---draft-postpage-file)\r\n\t- [🚧 `diff {prod|test}`](#-diff-prodtest)\r\n\t- [✅ `deploy {prod|test}`](#-deploy-prodtest)\r\n\t- [🚧 `server`](#-server)\r\n- [配置文件](#配置文件)\r\n\t- [`prod`字段](#prod字段)\r\n\t- [`test`字段](#test字段)\r\n\t- [`fields`字段](#fields字段)\r\n\t- [`defaultFields`字段](#defaultfields字段)\r\n\t- [`defaultSlugType`字段](#defaultslugtype字段)\r\n\t- [`repo`字段](#repo字段)\r\n- [使用注意事项](#使用注意事项)\r\n\t- [不得编辑的文件](#不得编辑的文件)\r\n\t- [可能出现的合并冲突](#可能出现的合并冲突)\r\n\t\t- [meta顺序更换问题](#meta顺序更换问题)\r\n\t\t- [以`cid`作为`slug`的问题](#以cid作为slug的问题)\r\n\r\n# 环境及依赖项\r\n\r\n- Client\r\n  - Python 3.6+\r\n  - Linux (WSL)\r\n  - Git\r\n  - MySQL (可选，用于本地测试服务器)\r\n  - PHP (可选，用于本地测试服务器)\r\n  - Python依赖项\r\n    - pyyaml\r\n    - click\r\n    - requests\r\n    - GitPython\r\n- Server\r\n  - Python 3.6+\r\n  - MySQL (目前仅支持此数据库)\r\n  - Python依赖项\r\n    - pyyaml\r\n    - pymysql\r\n    - pandas\r\n    - uvicorn\r\n    - requests\r\n    - fastapi\r\n    - typing\r\n    - pydantic\r\n\r\n# 术语\r\n\r\n- `prod` - 生产环境\r\n- `test` - 测试环境，即本地测试服务器\r\n- `workplace` ( `wp` ) - 工作区\r\n\r\n# 原理以及流程\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\t\u003cimg alt=\"workflow\" src=\"imgs/typexo.svg\"\u003e\r\n\u003c/div\u003e\r\n\r\n主要原理如上图。同一种颜色代表同一个流程；实线代表命令，虚线代表内部流程。\r\n\r\n本地使用`git`进行管理分支，总共有三个分支: \r\n\r\n- `master`: 主分支，用于编辑；\r\n- `prod`: 生产环境拉去下来的分支，用于`merge conflict`。注意：这个分支不得有任何改动，只能执行`typexo`的`pull prod`命令，自动完成。若出现错误，请执行`discard-change`命令；\r\n- `test`: 本地测试分支 (可选)。本地经过测试后，若想同步测试服务器上的结果，可以通过`pull test`命令`merge`到主分支，随后测试分支将被删除，是一个临时分支。\r\n\r\n注意：\r\n\r\n- 在本项目中，所有的`checkout` (切换分支) 操作的先决条件是 `working tree clean` ，如果还有更改没有提交，将会拒绝分支切换请求；\r\n- `test`分支在进行任意的合并操作之后会被自动删除，`prod`分支不会。如果没有合理的原因，请不要删除`prod`分支，否则会引发数据混乱；\r\n- 在进行`deploy`的时候，我们并没有采用`git`的两个分支之间的`diff`，而是直接再度拉取服务器端的数据，直接进行比对。这样做的原因其实只是`GitPython`这块文档写得太含糊了...\r\n\r\n# 准备就绪，开始！\r\n\r\n## 在服务器搭好`typexo-server`\r\n\r\n[typexo-server@使用方法](https://github.com/JeffersonQin/typexo-server#%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95)\r\n\r\n## 配置`config.yml`\r\n\r\n- 将`config_template.yml`复制重命名为`config.yml`\r\n- 按照[配置文件节](#配置文件)配置\r\n\r\n## Quick Start\r\n\r\n准备一个空文件夹 (`root_dir`)，讲`typexo-cli`克隆到该文件夹内：\r\n```\r\nroot_dir\r\n└── typexo-cli\r\n```\r\n\r\n初始化项目文件夹：\r\n\r\n```bash\r\npython3 typexo-cli/main.py init\r\n```\r\n\r\n会产生`workplace`目录：\r\n\r\n```\r\nroot_dir\r\n├── typexo-cli\r\n└── workplace\r\n```\r\n\r\n从生产环境拉取：\r\n\r\n```bash\r\npython3 main.py pull prod\r\n```\r\n\r\n最终目录结构：\r\n\r\n```\r\nroot_dir\r\n├── typexo-cli\r\n│   ├── README\r\n│   ├── README.md\r\n│   ├── cache\r\n│   ├── config.yml\r\n│   ├── config_template.yml\r\n│   ├── imgs\r\n│   ├── lib\r\n│   ├── main.py\r\n│   ├── server\r\n│   └── site\r\n└── workplace\r\n    ├── README.md\r\n    ├── cids-generated.json\r\n    ├── metas.json\r\n    ├── page_drafts\r\n    ├── pages\r\n    ├── post_drafts\r\n    └── posts\r\n```\r\n\r\n# 关于本地测试服务器\r\n\r\n我们的目标之一是能够像`Hexo`一样能够在本地搭建测试服务器，所以我们同时把`typexo-server`作为`submodule`引入了本项目。(这个功能相对独立，和其他部分无关)\r\n\r\n实现方法：在本地搭建`php`服务器和`typexo-server`.\r\n\r\n具体实现细节仍在考虑当中。\r\n\r\n# 命令说明\r\n\r\n注：✅代表已完成，❌代表未完成，🚧代表正在编写。\r\n\r\n## ✅ `init`\r\n\r\n初始化`workplace`。会在当前目录新建一个`workplace`文件夹，然后在其内部初始化`git`。\r\n\r\n## ✅ `rm`\r\n\r\n删除`workplace`。直接删除`workplace`文件夹，需要操作确认。\r\n\r\n## ✅ `commit`\r\n\r\n相当于对当前分支进行`git commit -am`，提交代码。\r\n\r\n## ✅ `discard-change`\r\n\r\n相当于对当前分支进行`git reset --hard HEAD`，会删除所有未提交更改，需要操作确认。\r\n\r\n## ✅ `status`\r\n\r\n相当于对当前分支进行`git status`，获取当前信息。\r\n\r\n## ✅ `merge {prod|test}`\r\n\r\n先切换到主分支，然后合并输入的分支 ( `prod` / `test` )\r\n\r\n## ✅ `fix-git-utf8`\r\n\r\n修复`git`在命令行中可能对中文产生的乱码现象。等价命令：\r\n\r\n```bash\r\ngit config --global core.quotepath false\t\t\t\t# 显示 status 编码\r\ngit config --global gui.encoding utf-8\t\t\t\t\t# 图形界面编码\r\ngit config --global i18n.commit.encoding utf-8\t\t\t# 提交信息编码\r\ngit config --global i18n.logoutputencoding utf-8\t\t# 输出 log 编码\r\n```\r\n\r\nReference: http://howiefh.github.io/2014/10/11/git-encoding/\r\n\r\n## ✅ `prod-test`\r\n\r\n对生产环境进行连通性测试。\r\n\r\n## ✅ `clone`\r\n\r\n从远程仓库拉取`workplace`，需要在`config.yml`中配置。\r\n\r\n## ✅ `pull {prod|test}`\r\n\r\n从 `prod` / `test` 环境导入到本地对应分支，并自动进行`merge`操作。\r\n\r\n## ✅ `push`\r\n\r\n将 `workplace` 推送到远程仓库，需要在`config.yml`中配置。\r\n\r\n## ✅ `format`\r\n\r\n格式化所有`markdown`文件，即自动对于各种`meta`进行排序。\r\n\r\n## ✅ `new [--draft] {post|page} TITLE`\r\n\r\n创建新内容。如果使用`--draft`选项则代表是草稿，`TITLE`是文章标题。\r\n\r\n## ✅ `import [--draft] {post|page} FILE`\r\n\r\n导入markdown文件。如果使用`--draft`选项则代表是草稿，`FILE`是文件路径。\r\n\r\n## 🚧 `diff {prod|test}`\r\n\r\n与远程`typexo-server`服务器传回的内容进行比对，列出更改 / 删除 / 增加过的项目。\r\n\r\n## ✅ `deploy {prod|test}`\r\n\r\n将内容更改上传到`prod` / `test`.\r\n\r\n## 🚧 `server`\r\n\r\n本地搭建`test`环境，导入`sql`表，搭建`typecho`的`php-server`\r\n\r\n# 配置文件\r\n\r\n## `prod`字段\r\n\r\n- [**只能在 Unix 下使用，用来解决跨时区编辑问题**] `timezone` - 时区。格式：`Asia/Shanghai`。\r\n- `token` - 生产环境的`typexo-server`的验证`token`\r\n- `url` - 生产环境`typexo-server`的访问链接\r\n\r\n## `test`字段\r\n\r\n- `token` - 测试环境的`typexo-server`的验证`token`\r\n- `url` - 测试环境`typexo-server`的访问链接\r\n\r\n## `fields`字段\r\n\r\n在看这一节之前，请先了解`typecho_fields`数据库，是存储文章自定义字段的数据库。参考资料：\r\n\r\n- [typexo-server API](https://github.com/JeffersonQin/typexo-server/blob/master/API.md)\r\n- [typecho 数据库设计](https://docs.typecho.org/database)\r\n\r\n由于官方对于自定义字段指定了三种`type`: \r\n\r\n- `str`\r\n- `int`\r\n- `float`\r\n\r\n所以一些常用类型，比如说`boolean`会产生错误。为此，专门设置这个字段来指明各个自定义字段的属性。配置示例：\r\n\r\n```yaml\r\nfields:\r\n  customField1: str\r\n  customField2: int\r\n  customField3: float\r\n```\r\n\r\n## `defaultFields`字段\r\n\r\n`defaultFields`字段的作用就是配置在新建文章的时候，需要默认生成的自定义字段。配置格式：\r\n\r\n```yaml\r\ndefaultFields:\r\n  fieldName: fieldValue\r\n```\r\n\r\n注意：对于`yes`, `no`, `true`, `false`等本身带有特殊含义可以被解析的值而言，请加上引号。\r\n\r\n## `defaultSlugType`字段\r\n\r\n可选项：`cid`, `title`. 指在生成新文章时，默认的`slug`内容。\r\n\r\n## `repo`字段\r\n\r\n- `url` - 远程 `git` 仓库地址\r\n\r\n# 使用注意事项\r\n\r\n## 不得编辑的文件\r\n\r\n* **请勿直接在`metas.json`内添加新的`meta`，如果需要添加并更改属性，请使用其他方式，如：直接在浏览器中进行此操作 / 将新`meta`添加到一篇文章中，在`deploy`后再在`metas.json`中进行进行编辑**\r\n* **请勿编辑`cids-generated.json`**\r\n\r\n## 可能出现的合并冲突\r\n\r\n### meta顺序更换问题\r\n\r\n由于文章的`meta`是自动生成的，所以在手动更改之后，可能与自动生成的不一致（比如说`tags`, `categories`中的顺序），为此，我们有时需要手动解决`conflict`。如下图：\r\n\r\n![](https://cdn.jsdelivr.net/gh/JeffersonQin/blog-asset@latest/usr/picgo/20210604202412.png)\r\n\r\n我们需要`accept incoming change`\r\n\r\n### 以`cid`作为`slug`的问题\r\n\r\n由于`slug`需要先`deploy`才能知道，所以拉去下来会出现`conflict`（因为增加了`slug`的信息）。在这种情况下，我们需要同时保留本地的更改和新增的`slug`信息，同时需要注意要按照指定的顺序（否则会出现错误）。如果不想出现这样的情况，那么可以不要以`cid`作为`slug`。可以在配置文件中设置。\r\n\r\n![](https://cdn.jsdelivr.net/gh/JeffersonQin/blog-asset@latest/usr/picgo/20210606135811.png)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffersonqin%2Ftypexo-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffersonqin%2Ftypexo-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffersonqin%2Ftypexo-cli/lists"}