mcp-thai-proofread

MCP server ที่ช่วยให้ AI agent ที่รองรับ MCP เช่น Hermes ตรวจและแก้คำสะกดภาษาไทยในไฟล์ Markdown หรือในข้อความได้โดยตรง ทำงานบน Docker ในโหมด streamable HTTP โดยใช้ LLM ผ่าน endpoint แบบ OpenAI-compatible เช่น OpenRouter, vLLM หรือ Ollama

ผู้พัฒนา: Chacharin Lertyosbordin

ระบบแก้เฉพาะการสะกดคำ โดยไม่เรียบเรียงเนื้อหาใหม่ และตรวจคำตอบของ LLM อีกชั้นหนึ่ง เพื่อไม่ให้ตัวเลข รหัสอ้างอิง URL หรือโครงสร้างของเอกสารเปลี่ยนไป

เครื่องมือที่มีให้

proofread_thai มีโหมด dry_run สำหรับดูรายการที่จะแก้ก่อนโดยยังไม่เปลี่ยนไฟล์

Related MCP server: SpellChecker MCP Server

หลักการทำงาน

agent ──POST /mcp──▶ mcp-thai-proofread (container)
                       ① ตรวจ token หากกำหนด MCP_AUTH_TOKEN ไว้
                       ② แบ่งเอกสารเป็นช่วง แล้วส่งให้ LLM ตรวจทีละช่วง
                       ③ ตรวจคำตอบของ LLM ทีละบรรทัด และปฏิเสธการแก้ไขที่เกินขอบเขต
                       ④ สำรองไฟล์ต้นฉบับ บันทึกไฟล์ที่แก้แล้ว และเขียนบันทึกการแก้ไข
                     ◀── ส่งสรุปผลกลับไปยัง agent

รายละเอียดของแต่ละขั้น:

1. ตรวจตำแหน่งไฟล์ ตัดคำนำหน้า path ที่ agent อาจส่งมา (PATH_PREFIXES) ตรวจว่าไฟล์อยู่ภายใน workspace และรับเฉพาะนามสกุลที่อนุญาต (FILE_EXTENSIONS)

2. แบ่งเอกสารเป็นช่วง เริ่มช่วงใหม่ทุกครั้งที่พบหัวข้อ หรือเมื่อความยาวเกิน CHUNK_CHARS ตัวอักษร โดยข้ามบล็อกโค้ดและบรรทัดที่ไม่มีภาษาไทย ซึ่งจะไม่ถูกส่งไปยัง LLM

3. แนบบริบท ส่งชื่อเอกสาร ลำดับหัวข้อ และบรรทัดก่อนหลังจำนวน CONTEXT_LINES บรรทัดไปด้วย เพื่อให้ LLM ใช้ประกอบการพิจารณาเท่านั้น

4. ส่งให้ LLM ตรวจ ส่งพร้อมกันครั้งละ WORKERS ช่วง และลองใหม่เมื่อได้รับ HTTP 429 หรือ 5xx หาก LLM ส่งจำนวนบรรทัดกลับมาไม่ครบ ระบบจะแบ่งช่วงนั้นครึ่งหนึ่งแล้วส่งใหม่

5. ตรวจผลทีละบรรทัด ระบบจะปฏิเสธการแก้ไขและคงข้อความเดิมไว้ หาก

   • ตัวเลข URL คำภาษาอังกฤษ รหัสที่ตรงกับ PROTECTED_REGEX หรือรูปแบบ Markdown (ตาราง ตัวหนา หัวข้อ รายการ) เปลี่ยนไป

   • หรือบรรทัดนั้นเปลี่ยนไปจากต้นฉบับมากกว่าเกณฑ์ MIN_SIMILARITY

6. บันทึกผล สำรองไฟล์ต้นฉบับก่อนเขียนทับ แล้วบันทึกว่าแก้บรรทัดใด และปฏิเสธการแก้ไขบรรทัดใดด้วยเหตุผลอะไร

ค่าใช้จ่ายขึ้นอยู่กับ LLM ที่เลือกและความยาวของเอกสาร เพราะทุกช่วงของเอกสารต้องส่งให้ LLM ตรวจหนึ่งครั้ง

สองวิธีในการเข้าถึง workspace

proofread_thai ต้องอ่านและเขียนไฟล์ชุดเดียวกับที่ agent ใช้งาน ระบบรองรับ 2 วิธี และเลือกให้เองตอนเริ่มทำงาน

โหมด hermes (คนละเครื่องได้)
agent ──POST /mcp──▶ mcp-thai-proofread ──HTTP──▶ Hermes dashboard ──▶ /opt/data/workspace
                                         GET  /api/files/read     (อ่านไฟล์)
                                         POST /api/files/upload   (สำรองไฟล์ บันทึกไฟล์ที่แก้ และบันทึกการแก้ไข)

โหมด local (เครื่องเดียวกัน)
agent ──POST /mcp──▶ mcp-thai-proofread ──▶ /workspace (โฟลเดอร์ที่ mount ไว้)

ทั้งสองโหมดให้ผลลัพธ์และสร้างไฟล์สำรองกับบันทึกการแก้ไขเหมือนกันทุกประการ ต่างกันเพียงช่องทางที่ใช้เข้าถึงไฟล์ หากมีทั้งโฟลเดอร์ที่ mount ไว้และบัญชี dashboard ระบบจะใช้โฟลเดอร์ก่อน

เริ่มต้นใช้งาน

สิ่งที่ต้องเตรียม

• Docker ที่เปิดใช้ BuildKit ซึ่ง Docker Desktop และ Docker Engine ตั้งแต่เวอร์ชัน 23.0 เปิดไว้เป็นค่าเริ่มต้นแล้ว หากพบข้อความ the --mount option requires BuildKit ระหว่าง build ให้อัปเดต Docker หรือสั่ง build ด้วย DOCKER_BUILDKIT=1 docker compose build

• การเชื่อมต่ออินเทอร์เน็ตระหว่าง build ครั้งแรก เพื่อดาวน์โหลด python:3.12-slim image ของ uv และไลบรารีจาก PyPI (หากองค์กรไม่อนุญาตให้เชื่อมต่ออินเทอร์เน็ต ต้องใช้ mirror ภายใน)

• LLM endpoint แบบ OpenAI-compatible พร้อม API key (หาก endpoint นั้นกำหนดให้ใช้) ควรเลือก model ที่รองรับภาษาไทยได้ดี เพราะคุณภาพการแก้ไขขึ้นอยู่กับ model โดยตรง

ไม่จำเป็นต้องติดตั้ง Python หรือ uv บนเครื่อง เพราะ Dockerfile จะใช้ uv เวอร์ชันที่ระบุไว้ติดตั้งไลบรารีตาม uv.lock เฉพาะระหว่าง build และไม่เก็บ uv ไว้ใน image ทุกเครื่องจึงได้ไลบรารีเวอร์ชันเดียวกัน

ขั้นตอนการติดตั้ง

git clone https://github.com/chacharin/mcp-thai-proof-md.git
cd mcp-thai-proof-md
cp .env.example .env                  # จากนั้นแก้ LLM_BASE_URL, LLM_API_KEY และ LLM_MODEL ในไฟล์ .env
docker network create agent_network   # สร้างครั้งแรกครั้งเดียว หากต้องการใช้ชื่ออื่นให้กำหนดใน DOCKER_NETWORK

จากนั้นเลือกวิธีเข้าถึง workspace ในไฟล์ .env ตามแบบใดแบบหนึ่ง

แบบที่ 1 ผ่าน dashboard ของ Hermes (server อยู่คนละเครื่องกับ Hermes ได้) ให้กำหนดค่าในหมวด --- workspace ---

HERMES_DASHBOARD_URL=http://hermes-dashboard:9119   # หรือ https://<เครื่องของ Hermes> เมื่ออยู่คนละเครื่อง
HERMES_DASHBOARD_USER=<ชื่อผู้ใช้ dashboard>
HERMES_DASHBOARD_PASSWORD=<รหัสผ่าน dashboard>
PATH_PREFIXES=/opt/data/workspace/                  # Hermes อ้างถึงไฟล์ด้วย path นี้

แบบที่ 2 mount โฟลเดอร์ (server อยู่เครื่องเดียวกับ agent) ให้เพิ่มไฟล์ docker-compose.same-host.yml เข้าไปในการสั่ง compose

COMPOSE_FILE=docker-compose.yml:docker-compose.same-host.yml   # บน Windows ใช้ ; คั่นแทน :
WORKSPACE_HOST_DIR=./workspace                                 # โฟลเดอร์บนเครื่องที่เก็บไฟล์ที่ต้องการตรวจ

เมื่อกำหนด COMPOSE_FILE ไว้ใน .env แล้ว คำสั่ง docker compose ทุกคำสั่งจะใช้ทั้งสองไฟล์เอง จึงไม่ต้องระบุ -f ทุกครั้ง

จากนั้นเริ่มระบบและตรวจสถานะ

docker compose up -d --build
curl http://127.0.0.1:8805/health

หาก /health ตอบ "ok": true และ workspace.reachable เป็น true แปลว่าการตั้งค่า LLM พร้อมใช้งานและเข้าถึง workspace ได้แล้ว หากยังมีปัญหา ให้ดูรายการ problems ซึ่งจะบอกสาเหตุ เช่น ยังใช้ LLM_API_KEY ตัวอย่างจาก .env.example หรือ dashboard ปฏิเสธรหัสผ่าน

/health ไม่ได้เรียก LLM จริง หากต้องการทดสอบให้แน่ใจว่า LLM ตอบได้ ให้สั่ง (เรียก LLM จริงหนึ่งครั้ง):

docker exec mcp-thai-proofread /app/.venv/bin/python -m app.selftest
docker exec mcp-thai-proofread /app/.venv/bin/python -m app.selftest --file report.md   # ตรวจไฟล์จริงโดยไม่แก้ไขไฟล์

คำอธิบายการตั้งค่าทั้งหมดอยู่ในไฟล์ .env.example โดยในไฟล์ .env ให้กำหนดเฉพาะค่าที่จำเป็น และค่าที่ต้องการเปลี่ยนจากค่าเริ่มต้น เมื่อแก้ไข .env แล้ว ให้สั่ง docker compose up -d อีกครั้ง โดยไม่ต้อง build ใหม่

การเชื่อมต่อกับ MCP client

ตัวอย่างการตั้งค่าใน Hermes (config.yaml):

mcp_servers:
  thai_proofread:
    url: http://mcp-thai-proofread:8800/mcp
    timeout: 900          # ไฟล์ยาวอาจใช้เวลาหลายนาที ควรนานกว่า LLM_TIMEOUT_SECONDS
    connect_timeout: 60

หาก timeout ของ client สั้นกว่าเวลาที่ใช้ตรวจจริง client จะแจ้งว่าการเรียกล้มเหลว ทั้งที่ server ยังแก้ไขไฟล์ต่อไปอยู่

agent ต้องมองเห็นไฟล์ชุดเดียวกับ server

• หาก agent อ้างถึงไฟล์ด้วย path ภายในเครื่องของตัวเอง เช่น Hermes ส่ง /opt/data/workspace/report.md ให้กำหนด PATH_PREFIXES=/opt/data/workspace/ เพื่อให้ระบบตัดคำนำหน้านั้นออก

• โหมด hermes ใช้ workspace ของ Hermes เสมอ (HERMES_WORKSPACE ค่าเริ่มต้น /opt/data/workspace) ไฟล์ที่แก้แล้วจึงเป็นไฟล์เดียวกับที่ agent เห็นทันที

• โหมด local ต้อง mount โฟลเดอร์เดียวกันให้ทั้งสองฝั่ง และกำหนด RUN_UID กับ RUN_GID ให้ตรงกับเจ้าของ workspace เพื่อให้ทั้ง agent และ server ยังเขียนไฟล์ที่แก้แล้วได้

หากกำหนด MCP_AUTH_TOKEN ไว้ ให้เพิ่ม header Authorization: Bearer <token> ในการตั้งค่าของ client ด้วย สำหรับ client ที่อยู่นอก docker network ให้ใช้ http://<IP ของเครื่อง>:8805/mcp

วิธีใช้งาน

เมื่อเชื่อมต่อแล้ว ผู้ใช้เพียงพิมพ์สั่ง agent ด้วยภาษาปกติ agent จะเลือกเครื่องมือและกรอกค่าให้เอง หัวข้อนี้อธิบายว่าแต่ละงานควรสั่งอย่างไร และเครื่องมือรับค่าอะไรบ้าง

1. ตรวจและแก้ไฟล์

ตัวอย่างคำสั่ง:

ตรวจคำสะกดภาษาไทยในไฟล์ report.md ให้หน่อย ตรวจภาษาไทยของ project-a/chapter1.md แต่ยังไม่ต้องแก้ไฟล์ ขอดูก่อนว่าจะแก้อะไรบ้าง

agent จะเรียก proofread_thai

เมื่อแก้ไฟล์จริง ระบบจะสร้างไฟล์ 2 ไฟล์ใน <โฟลเดอร์>

<โฟลเดอร์> กำหนดได้ด้วย OUTPUT_PLACEMENT ได้แก่ file (ค่าเริ่มต้น) คือโฟลเดอร์เดียวกับไฟล์ที่แก้ไข และ top คือโฟลเดอร์ชั้นแรกใต้ workspace ซึ่งเหมาะกับการรวมไฟล์สำรองของทั้งโปรเจกต์ไว้ในที่เดียว เปลี่ยนชื่อโฟลเดอร์ย่อยได้ด้วย BACKUP_SUBDIR และ NOTES_SUBDIR หากกำหนด NOTES_SUBDIR เป็นค่าว่าง ระบบจะไม่เขียนบันทึก

ตัวอย่างบันทึกการแก้ไข:

## ตรวจภาษาไทย 20261019-203654 · google/gemma-4-31b-it

- ไฟล์: `meeting.md` · ส่งตรวจ 1 ช่วง · แก้ 2 บรรทัด · ปฏิเสธการแก้ไข 0 บรรทัด
- จุดที่น่าสงสัย (ตรวจด้วยรูปแบบ) ก่อน/หลัง: 0 / 0

- บรรทัด 3
  - เดิม: ที่ประชุมอนุญาติให้ใช้งบประมาณ 2.5 ล้านบาท ตามข้อเสนอ [S1]
  - แก้: ที่ประชุมอนุญาตให้ใช้งบประมาณ 2.5 ล้านบาท ตามข้อเสนอ [S1]

หากต้องการย้อนกลับ ให้คัดลอกไฟล์จาก backups/ กลับมาแทนไฟล์ที่แก้แล้ว ไฟล์ขนาดไม่กี่ย่อหน้าใช้เวลาไม่กี่วินาที แต่เอกสารยาวอาจใช้เวลาหลายนาที

2. ตรวจข้อความที่ไม่ได้อยู่ในไฟล์

ตัวอย่างคำสั่ง:

ช่วยตรวจคำสะกดของย่อหน้านี้ก่อนส่งอีเมล: … ร่างคำตอบเสร็จแล้ว ตรวจภาษาไทยให้ด้วยก่อนส่งให้ผม

agent จะเรียก proofread_text

ผลลัพธ์คือข้อความทั้งหมดที่แก้แล้ว พร้อมรายการบรรทัดที่แก้และบรรทัดที่ปฏิเสธการแก้ไข โดยไม่มีการอ่านหรือเขียนไฟล์ใด ๆ

3. อ่านผลลัพธ์ให้ถูกต้อง

เหตุผลที่ระบบปฏิเสธการแก้ไขมี 3 แบบ

รูปแบบ JSON ของคำขอและผลลัพธ์

mcp-thai-proofread มี 3 route

การส่งคำขอไปที่ /mcp

ทุกคำขอต้องมี header สองตัวนี้ (และ Authorization: Bearer <token> หากกำหนด MCP_AUTH_TOKEN)

Content-Type: application/json
Accept: application/json, text/event-stream

ผลลัพธ์จะส่งกลับในรูปแบบ Server-Sent Events คือมีบรรทัด event: message แล้วตามด้วย data: <JSON> ตัวอย่างต่อไปนี้แสดงเฉพาะส่วน JSON และจัดบรรทัดใหม่ให้อ่านง่าย

ผลลัพธ์ของทุกเครื่องมืออยู่ใน result.content[0].text เป็นข้อความ JSON ตัวอย่างด้านล่างจึงแสดงค่า text ในรูป JSON ที่แปลงกลับแล้ว เพื่อให้อ่านง่าย

ดูรายการเครื่องมือ (tools/list)

คำขอ:

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

ผลลัพธ์ (ย่อ):

{"jsonrpc": "2.0", "id": 1, "result": {"tools": [
  {
    "name": "proofread_thai",
    "description": "ตรวจและแก้คำสะกดภาษาไทยในไฟล์ใน workspace แล้วบันทึกทับไฟล์เดิม …",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path":    {"type": "string", "description": "ตำแหน่งไฟล์เทียบกับราก workspace เช่น \"report.md\" … (รับเฉพาะไฟล์นามสกุล .md)"},
        "dry_run": {"type": "boolean", "default": false, "description": "true = ตรวจอย่างเดียว …"}
      },
      "required": ["path"]
    },
    "annotations": {"readOnlyHint": false, "destructiveHint": false, "openWorldHint": true}
  },
  {"name": "proofread_text", "…": "…"}
]}}

ตรวจและแก้ไฟล์ (proofread_thai)

ไฟล์ meeting.md ที่ใช้ในตัวอย่าง:

# รายงานการประชุม

ที่ประชุมอนุญาติให้ใช้งบประมาณ 2.5 ล้านบาท ตามข้อเสนอ [S1]
ผลลัพท์ของการทดลองแสดงว่ามีโอกาศสำเร็จสูง

คำขอ:

{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {
  "name": "proofread_thai",
  "arguments": {"path": "meeting.md"}
}}

ค่า text ในผลลัพธ์:

{
  "ok": true,
  "file": "meeting.md",
  "model": "google/gemma-4-31b-it",
  "dry_run": false,
  "chunks": 1,
  "lines_changed": 2,
  "lines_rejected": 0,
  "suspect_before": 0,
  "suspect_after": 0,
  "errors": [],
  "seconds": 3.3,
  "backup": "backups/meeting.md.bak-proof-20261019-203654",
  "sample_changes": [
    {"before": "ที่ประชุมอนุญาติให้ใช้งบประมาณ 2.5 ล้านบาท ตามข้อเสนอ [S1]",
     "after":  "ที่ประชุมอนุญาตให้ใช้งบประมาณ 2.5 ล้านบาท ตามข้อเสนอ [S1]"},
    {"before": "ผลลัพท์ของการทดลองแสดงว่ามีโอกาศสำเร็จสูง",
     "after":  "ผลลัพธ์ของการทดลองแสดงว่ามีโอกาสสำเร็จสูง"}
  ],
  "log": "notes/proofread-meeting.md"
}

ตัวเลข 2.5 และรหัส [S1] ยังเหมือนเดิม sample_changes แสดงไม่เกิน 10 บรรทัดแรก ส่วนรายการทั้งหมดอยู่ในไฟล์ log เมื่อส่ง "dry_run": true ผลลัพธ์จะไม่มี backup และ log แต่มี changes (พร้อมเลขบรรทัด) และ rejected แทน

ตรวจข้อความ (proofread_text)

คำขอ:

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {
  "name": "proofread_text",
  "arguments": {"text": "ผลลัพท์ของการทดลองแสดงว่ามีโอกาศสำเร็จสูง", "title": "รายงานการทดลอง"}
}}

ค่า text ในผลลัพธ์:

{
  "ok": true,
  "model": "google/gemma-4-31b-it",
  "text": "ผลลัพธ์ของการทดลองแสดงว่ามีโอกาสสำเร็จสูง",
  "lines_changed": 1,
  "lines_rejected": 0,
  "changes": [
    {"line": 1, "before": "ผลลัพท์ของการทดลองแสดงว่ามีโอกาศสำเร็จสูง", "after": "ผลลัพธ์ของการทดลองแสดงว่ามีโอกาสสำเร็จสูง"}
  ],
  "rejected": [],
  "errors": []
}

รายการใน rejected มีรูปแบบ {"line": 4, "reason": "<เหตุผล>", "before": "<ข้อความเดิม>", "suggested": "<ข้อความที่ LLM เสนอ>"}

ข้อผิดพลาด

ทุกกรณีที่เรียก LLM ไม่สำเร็จ ช่วงนั้นจะคงข้อความเดิมไว้ ไฟล์จึงไม่เสียหาย

ตรวจสถานะ (GET /health)

{
  "ok": true,
  "model": "google/gemma-4-31b-it",
  "base_url": "https://openrouter.ai/api/v1",
  "key_configured": true,
  "workspace": {"mode": "hermes", "root": "/opt/data/workspace", "reachable": true},
  "usage_log": {"enabled": true, "dir": "/app/usage", "writable": true, "last_error": null},
  "auth": false,
  "problems": []
}

workspace.mode บอกโหมดที่ระบบเลือก (hermes หรือ local และเป็น null เมื่อไม่มี workspace) ส่วน reachable บอกว่าเข้าถึงได้จริงหรือไม่ ในโหมด hermes ค่านี้ได้จากการเข้าสู่ระบบ dashboard และเปิดโฟลเดอร์ workspace จริงหนึ่งครั้ง หากไม่มี workspace เลย proofread_text ยังใช้งานได้ตามปกติ

เมื่อมีปัญหา ok จะเป็น false และ problems จะบอกสาเหตุพร้อมวิธีแก้ เช่น "LLM_API_KEY is still the example value from .env.example - put your real key in .env"

ข้อมูลการใช้งาน (GET /usage)

ระบบบันทึกการเรียก LLM ทุกครั้ง และสรุปของการเรียกเครื่องมือแต่ละครั้ง ลงไฟล์ usage-<วันที่>.jsonl ใน docker volume usage เพื่อใช้วิจัยและปรับประสิทธิภาพ เช่น เทียบ model ผู้ให้บริการ หรือขนาดช่วงข้อความ (CHUNK_CHARS) ระเบียนมีเฉพาะจำนวน token ขนาด และเวลา ไม่มีข้อความที่ตรวจ

ผลลัพธ์ของ GET /usage?since=1792466000 (ย่อ):

{
  "schema": "harness-usage/1",
  "environment": {"component": "mcp-thai-proofread", "version": "0.3.0", "host": "3f2a…", "cpu_count": 20, "mem_total_mb": 11816, "…": "…"},
  "records": [
    {"kind": "llm_call", "tool": "proofread_text", "request_id": "9c1e…", "model": "google/gemma-4-31b-it",
     "upstream_provider": "Google", "endpoint_host": "openrouter.ai", "duration_s": 2.015,
     "input_tokens": 480, "cache_read_tokens": 0, "output_tokens": 6, "reasoning_tokens": 0, "total_tokens": 486,
     "cost_usd": 5.004e-05, "output_tps": 2.98, "status": "ok", "detail": {"attempts": 1, "request_chars": 1342, "answer_chars": 17}},
    {"kind": "mcp_tool", "tool": "proofread_text", "request_id": "9c1e…", "duration_s": 2.019, "total_tokens": 486,
     "cost_usd": 5e-05, "status": "ok", "detail": {"llm_calls": 1, "llm_seconds": 2.015, "text_chars": 17, "chunks": 1, "lines_changed": 1}}
  ]
}

• llm_call หนึ่งระเบียนต่อการเรียก LLM หนึ่งครั้ง (หนึ่งช่วงข้อความ) ส่วน mcp_tool คือสรุปของการเรียกเครื่องมือหนึ่งครั้ง ทั้งสองใช้ request_id เดียวกัน

• ตัวเลข token และ cost_usd มาจากผู้ให้บริการ (OpenRouter รายงานค่าใช้จ่ายจริง) หากผู้ให้บริการไม่รายงาน ค่าจะเป็น null

• ชื่อช่องข้อมูลเป็นแบบเดียวกับ plugin usage-telemetry ของ osint-harness-profile และ MCP ตัวอื่นของชุดนี้ จึงรวมเป็นชุดข้อมูลเดียวกันได้

ทดลองด้วย curl

curl http://127.0.0.1:8805/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"proofread_text","arguments":{"text":"มีโอกาศสำเร็จสูง"}}}'

บน Windows คำสั่ง curl อาจส่งภาษาไทยที่พิมพ์ในบรรทัดคำสั่งผิดเพี้ยนเป็น ? ให้บันทึก JSON ของคำขอเป็นไฟล์ UTF-8 เช่น request.json แล้วส่งด้วย -d @request.json แทน

การปรับให้เหมาะกับงานของคุณ

ค่าต่อไปนี้เป็นตัวแปรในไฟล์ .env ซึ่งไม่จำเป็นต้องกำหนด หากไม่กำหนด ระบบจะใช้ค่าเริ่มต้น เมื่อต้องการปรับ ให้เพิ่มบรรทัด ชื่อตัวแปร=ค่า ลงในไฟล์ .env แล้วสั่ง docker compose up -d (คำอธิบายและค่าเริ่มต้นของทุกตัวแปรดูได้ใน .env.example)

• PROTECTED_REGEX regex ของรหัสที่ห้ามเปลี่ยน ค่าเริ่มต้นตรวจรหัสอ้างอิงรูปแบบ [S1] [F12] และรวมหลายรูปแบบได้ด้วย | เช่น \[[A-Z]{1,3}\d+\]|มาตรา\s?\d+

• MIN_SIMILARITY เกณฑ์ความคล้ายกับต้นฉบับ (0–1) ค่ายิ่งสูง ระบบยิ่งเข้มงวดกับการแก้ไขที่เปลี่ยนข้อความมาก

• CHUNK_CHARS, CONTEXT_LINES และ WORKERS ขนาดของแต่ละช่วงที่ส่งให้ LLM จำนวนบรรทัดบริบท และจำนวนช่วงที่ส่งพร้อมกัน หากพบ rate limit (HTTP 429) บ่อย ให้ลด WORKERS

• FILE_EXTENSIONS, OUTPUT_PLACEMENT, BACKUP_SUBDIR และ NOTES_SUBDIR นามสกุลไฟล์ที่แก้ได้ และตำแหน่งของไฟล์สำรองกับบันทึกการแก้ไข

• USAGE_LOG และ USAGE_DIR เปิด/ปิดการบันทึกข้อมูลการใช้งาน และโฟลเดอร์ที่เก็บ (ดูข้อมูลการใช้งาน)

• LLM_EXTRA_PARAMS ค่าเพิ่มเติมที่ส่งไปกับทุกคำขอถึง LLM ในรูปแบบ JSON เช่น {"top_p": 0.9} หรือการเลือก provider ของ OpenRouter {"provider": {"order": ["google-vertex"]}}

การปรับ prompt

prompt ที่มากับระบบเป็นแบบทั่วไป มีเนื้อหาเดียวกับไฟล์ prompts/system_prompt.example.md หากต้องการปรับให้เหมาะกับงาน เช่น เอกสารราชการ กฎหมาย หรือการแพทย์:

cp prompts/system_prompt.example.md prompts/system_prompt.md   # จากนั้นแก้ไขไฟล์นี้
echo "SYSTEM_PROMPT_FILE=/app/prompts/system_prompt.md" >> .env
docker compose up -d

prompt ที่แก้ไขแล้วยังต้องสั่งให้ LLM ส่งกลับเฉพาะบรรทัดที่ต้องตรวจ ในจำนวนและลำดับเดิม โดยไม่มีคำอธิบายเพิ่มเติม มิฉะนั้นระบบจะปฏิเสธการแก้ไขของช่วงนั้นทั้งหมด ไฟล์ในโฟลเดอร์ prompts/ ที่ไม่ใช่ *.example.md จะไม่ถูก commit เนื่องจากอาจมีชื่อองค์กรอยู่

ความปลอดภัย

• ค่าเริ่มต้นไม่มีการยืนยันตัวตน และเปิดพอร์ต 8805 ให้เครื่องอื่นในเครือข่ายเข้าถึงได้ (PUBLISH_ADDR=0.0.0.0) ผู้ที่เข้าถึงพอร์ตนี้ได้จะสั่งแก้ไฟล์ใน workspace และใช้โควตา LLM ของคุณได้ทันที หากไม่จำเป็น ให้กำหนด PUBLISH_ADDR=127.0.0.1 ซึ่ง agent ที่อยู่ใน docker network เดียวกันจะยังเรียกใช้ได้ตามปกติ หรือกำหนด MCP_AUTH_TOKEN เพื่อบังคับให้ผู้เรียกต้องส่ง token

• ทั้งสองโหมดเขียนไฟล์ได้ เพราะเครื่องมือต้องแก้ไฟล์ ระบบรับเฉพาะ path ที่อยู่ภายใน workspace และทุกการแก้ไขจะมีไฟล์สำรองเสมอ

• ในโหมด hermes รหัสผ่าน dashboard เปิดสิทธิ์ทั้งหน้า dashboard ของ Hermes ไม่ใช่เฉพาะไฟล์ จึงควรเก็บไว้ใน .env เท่านั้น และเมื่อ server อยู่คนละเครื่องกับ Hermes ควรเชื่อมผ่าน HTTPS หรือเครือข่ายส่วนตัว (VPN) เพื่อไม่ให้รหัสผ่านและเนื้อหาไฟล์ถูกส่งแบบไม่เข้ารหัส API ไฟล์ของ Hermes ไม่ยอมให้อ่านไฟล์ค่าลับ เช่น .env อยู่แล้ว และระบบนี้เรียกเฉพาะไฟล์ภายใต้ HERMES_WORKSPACE

• API key ของ LLM ถูกเก็บไว้ในไฟล์ .env เท่านั้น ไม่ถูกส่งให้ agent และไฟล์นี้จะไม่ถูกส่งขึ้น git

• ข้อมูลการใช้งาน (/usage) ไม่มีข้อความที่ตรวจ มีเฉพาะจำนวน token ขนาด เวลา และชื่อไฟล์ไม่ถูกบันทึก แต่ยังบอกปริมาณการใช้งานได้ จึงใช้ token เดียวกับ /mcp เมื่อกำหนด MCP_AUTH_TOKEN

สำหรับนักพัฒนา

โค้ดหลักอยู่ในโฟลเดอร์ app/

ชุดทดสอบในโฟลเดอร์ tests/ ใช้ LLM จำลอง จึงไม่ต้องมี LLM จริงและไม่เสียค่าใช้จ่าย สั่งทดสอบผ่าน Docker ได้โดยไม่ต้องติดตั้ง Python:

docker run --rm -v "$PWD:/w" -w /w -e UV_PROJECT_ENVIRONMENT=/tmp/venv python:3.12-slim \
  sh -c "pip install -q uv==0.13.1 && uv run --frozen pytest -q -p no:cacheprovider"

หากติดตั้ง uv ไว้บนเครื่อง สั่ง uv run pytest ได้เลย

ไลบรารีทุกตัวถูกล็อกเวอร์ชันไว้ใน uv.lock หากแก้ pyproject.toml ให้เปลี่ยน uv run --frozen pytest ... ในคำสั่งข้างต้นเป็น uv lock แล้ว commit ไฟล์ uv.lock ที่เปลี่ยนไป หากใช้ PowerShell ให้เปลี่ยน $PWD เป็น ${PWD} และใช้ ` แทน \ สำหรับขึ้นบรรทัดใหม่

สัญญาอนุญาต

MIT © 2026 Chacharin Lertyosbordin